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

Annotations declare readOnlyHint=true, which is consistent with the description. The description adds transparency by detailing the data sources (in-memory ring vs SQLite), the env var requirement, and the exact return structure. No contradictions or missing critical behavior.

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

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

The description is two sentences long and front-loads the purpose. Every word adds value; no fluff. The structure is efficient and easy to parse.

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

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

Despite having no output schema, the description explicitly lists the return structure, making it complete. Given the tool's simplicity (one parameter) and the richness of the description, the agent has all necessary context.

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 single parameter (window). The description goes beyond the schema by explaining the semantics of each enum value and the opt-in requirement, adding significant value for agent comprehension.

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 'Per-tool latency analysis,' which clearly states the tool's purpose and resource. It distinguishes itself from siblings, none of which perform latency analysis, so an agent can easily identify when to use this tool.

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

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

The description explains the behavior for each window value ('session' vs longer windows) and the prerequisite for longer windows (env var). While it doesn't explicitly list when not to use or alternative tools, the guidance is clear and context-specific, earning a 4.

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 fully explains behavior: idempotent capture, default threshold, and the purpose of detecting silent upgrades. Annotations indicate readOnlyHint=false, and the description confirms write operations (capture). No contradictions.

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

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

Three concise sentences, no fluff, front-loaded with purpose. Every sentence adds value.

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

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

Given the tool's complexity (3 optional params, no output schema), the description covers inputs, behavior, defaults, and use case thoroughly. No gaps remain.

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

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

Schema coverage is 100%, but the description adds context beyond schema: it explains default behavior without args, idempotency of capture, and the significance of the threshold. This adds value for an agent.

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

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

The description clearly states the tool is an 'Embedding-drift canary' and explains its two modes (re-embedding or capturing). It distinguishes from sibling tools by focusing on drift detection, unlike the document retrieval tools.

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

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

The description explains when to use the tool: for detecting silent model upgrades. It provides guidance on the two main use cases (capture vs. check) and the threshold parameter, though it doesn't explicitly state when not to use it.

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 only readOnlyHint in annotations, the description carries the return-contract burden (no output schema exists) and does so well: it names the five verdict fields, the up-to-5 ranked blockers, and recommended_action. It also confirms the read-only guarantee. What is missing is any note on cost/latency of the fused transitive BFS or error/failure behavior.

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

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

Two sentences, front-loaded with the purpose question, then the mechanics. The parenthetical field lists are dense but each field earns mention because no output schema documents the return shape. Slightly list-heavy but not padded.

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

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

For a four-parameter, read-only aggregate with no output schema, the description covers purpose, return fields and the read-only contract adequately. Gaps are minor: no mention of the ambiguous-anchor refusal path (documented in the schema) and no coverage of the `repo` parameter.

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

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

Schema coverage is 75%, just under the high-coverage baseline, so the schema does most of the work on section_id, recent_edit_days and transitive_depth. The description adds real meaning by tying recent_edit_days to recently_edited_blocking and transitive_depth to the doc-level backlink signal, but the bare `repo` parameter gets no semantic help anywhere.

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

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

"Composite preflight: is this section safe to delete?" states a specific verb (preflight/check) and resource (section deletion safety), and enumerates the four signals it fuses so the agent understands this is an aggregation tool, not a single-signal lookup. It never names the closest siblings (get_backlinks, get_section_blast_radius), so the differentiation must be inferred from "composite."

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?

"Preflight" establishes the usage context clearly: call this before deleting a section, to obtain a single go/no-go verdict. There are no explicit exclusions or named alternatives (e.g., "use get_backlinks for raw backlink lists"), so the agent must infer when the composite is overkill.

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

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

Annotations only declare readOnlyHint=true. The description adds valuable behavioral context: 'Returns the count only, never the matching sections,' clarifying return behavior and reinforcing the read-only nature. It doesn't contradict annotations but could mention what happens with no matches or errors, though not essential.

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, information-dense sentence. It includes the version, purpose, filter list, usage guidance, and return behavior without any fluff. Every phrase 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?

Despite having no output schema and readOnlyHint only, the description provides a complete picture: what it does, the filters, the use cases, and the exact return value. For a simple count tool with 12 params and zero schema coverage, this is exemplary.

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

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

Schema description coverage is 0%, so the description must compensate. It lists and groups parameters ('path_glob, role/roles/exclude_roles, tags/exclude_tags, min/max_level, min/max_byte_length') and refers to search_sections for context, but doesn't detail each parameter's exact format or behavior. This adds meaning beyond the raw 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 'count sections matching the same filter set as search_sections' with a specific verb and resource, and distinguishes it from the sibling tool by noting 'skip ranking.' This explicitly differentiates it from search_sections and other related 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?

Explicitly states when to use: 'Use for UI counters or "does anything match?" probes.' It also implies when not to use (when ranking is needed) by the contrast with search_sections, and names the alternative tool explicitly.

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

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

Adds persistence details (file path, JSONC format, hand-edits welcome) beyond the readOnlyHint=false annotation, which signals mutation. No contradictions.

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

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

Two sentences, no fluff, front-loaded with the core action and important edge case. Every sentence adds value.

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

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

Given 2 params, no output schema, and simple annotations, description covers action, version, edge case, and persistence. Lacks return value description, but overall sufficient.

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

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

Schema coverage is 0%, so description must cover parameter meaning. Describes 'repos' behavior (empty list deletes) but does not explain 'name' beyond being a string. Partial compensation.

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?

Clearly states the tool creates, replaces, or deletes a repo group, with specific behavior on empty repos list. Distinguishes from sibling 'list_repo_groups' and other mutation 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?

Specifies minimum version (v1.26+) and a key edge case (empty repos deletes group). Lacks explicit when-not-to-use or alternative tools, but context is clear.

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

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

The annotation readOnlyHint: false already indicates a mutation, but the description adds key behavioral traits: it permanently deletes cached files while guaranteeing source safety, and explicitly states there is no undo. This goes beyond the annotation by explaining up-front the irreversible nature and the safety boundary.

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 short, fact-dense sentences. Each sentence adds value: purpose, safety guarantee, and irreversibility warning. There is no wasted wording or redundancy beyond reinforcing the key idea.

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

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

For a simple deletion tool with one parameter, no output schema, and limited complexity, the description is comprehensive enough. It covers the essential characteristics—what is deleted, safety, and irreversibility. It does not exhaustively list all edge cases but is complete for the use case.

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 covers 100% of the only parameter ('repo') with a clear description (owner/repo or repo name), so the description adds no additional parameter detail. It does not need to, since the schema is self-sufficient.

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 removes a repo index and its cached raw files, explicitly clarifying it never touches source documents. This distinguishes it from the many read-only sibling tools (e.g., get_doc_coverage, get_toc) and the indexing tools like index_local.

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

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

It implicitly tells when to use it (to remove an index) and warns about irreversibility, but it does not explicitly contrast with alternatives or state when NOT to use it. There is no mention of reverting or updating an index in place, so the guidance is adequate but not explicit.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered; the description usefully adds that it performs 'No content reads' and specifies the bundle of data returned. That is real behavioral context beyond the annotation, though it says nothing about pagination or failure behavior.

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

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

Two tight sentences: the first front-loads the version note and defines the returned bundle, the second justifies the tool against its alternatives. 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?

With no output schema, the description carries the burden of describing returns and does so concretely (metadata, breadcrumb, neighbors). A minor gap remains around ordering/limits of the neighbor set, but for a read-only two-parameter tool 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?

Schema description coverage is 100%, with both repo and section_id documented in the schema (including the v1.147+ anchor/reference mode and its ambiguity fields). The description adds no parameter syntax or semantics beyond what the schema already provides, so 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?

States a specific resource (one section) and enumerates exactly what the call returns: full metadata, ancestor breadcrumb, and prev/next/parent/first_child neighbors. It explicitly contrasts with the three sibling tools it replaces (get_section_summary + get_section_path + section_neighbors), so an agent can distinguish it without opening a 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?

Names the alternatives ('vs calling get_section_summary + get_section_path + section_neighbors separately') and gives the reason to prefer this tool: it saves three round-trips. That is clear when-to-use guidance, though it stops short of stating exclusions (e.g., when the narrower single-purpose tools are still preferable).

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

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

Annotations declare readOnlyHint=true, which is consistent with the described pure function. Description adds return structure details (per-axis deltas, grade change, etc.) and threshold behavior beyond 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, no filler. Front-loads purpose and key detail on input source. Every sentence is valuable.

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?

Describes inputs, outputs, and threshold. Lacks mention of error handling or data format assumptions, but overall sufficient for a bounded diff 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% with basic descriptions. Description adds valuable context that parameters should be `radar` sub-fields from responses, enhancing meaning beyond 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 the tool diffs two doc_health_radar payloads, with specific verb and resource. It distinguishes from sibling tools that perform other operations like listing or getting.

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 to pass the `radar` sub-field from two responses and suggests use case (yesterday vs today). No exclusions mentioned, but context is clear.

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

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

With readOnlyHint=true annotation present, the description adds value by clarifying it 'Grades the index, not the prose; none of the six axes read the writing itself,' which is useful behavioral context beyond the annotation. No contradiction found.

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 somewhat repetitive, listing the six axes in the first sentence and then again in the third sentence. It also includes extraneous details about mirroring jcm's and jData's health-radar shape, which could be trimmed without losing essential 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?

The description explains the output (axes 0-100, composite grade A-F) and notes what it does not read, but it omits the meaning of the 'repo' parameter and does not describe the health calculation methodology. Overall, it provides partial context but leaves some gaps.

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

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

The schema has one parameter 'repo' with no description, and the tool description does not explain what 'repo' refers to. Since schema coverage is 0%, the description fails to compensate, leaving the parameter semantics ambiguous.

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

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

The description clearly states the tool's function: 'Six-axis health radar for a doc repo' and enumerates the six axes. It also distinguishes it from its sibling diff_doc_health_radar by noting it pairs with that tool for snapshot deltas.

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 mentions pairing with diff_doc_health_radar for snapshot deltas, implying this tool is for current health snapshots. However, it does not explicitly state 'use this when you need current health' or provide exclusions for when to use 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 only supply readOnlyHint=false, so the description carries the rest and does so richly: file-type scope, return-shape guarantees (changes capped at 50, counts are authoritative over len), the commit-date vs naive-local-time distinction, and v1.147+ duplicate_anchors fields with their caps. This is exactly the behavioral context an agent needs for a mutating indexer.

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

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

Dense but front-loaded: the purpose sentence leads, followed by the scoping rule, then return-value and versioning detail. Every sentence carries operational information (caps, offsets, authoritative counts) rather than filler.

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

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

With no output schema, the description must explain return values and it does so thoroughly (changes, changes_total, duplicate_anchors family, mtime semantics). Coverage of embeddings/incremental/ref prerequisites is adequate for a 6-param mutating tool, though it never states permissions or failure/auth behavior.

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 every parameter is already documented in the schema. The description largely restates embedding-provider and incremental behavior already present there, adding little syntax or format detail beyond the schema baseline.

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

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

States a specific verb and resource ('Index a GitHub repository's documentation') and immediately explains the mechanism (fetches .md/.txt, parses sections, saves locally). It is clearly distinguished from the sibling index_local by calling out its differing mtime 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?

Gives concrete context: embedding auto-enablement conditions, the fact that .md/.txt are indexed and all else ignored, and how index_local differs. However, it never explicitly states when to choose this tool over index_local (e.g. remote URL vs local path), leaving the routing to inference.

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

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

Beyond the readOnlyHint annotation, the description adds behavioral details: results are scoped to the active storage_path, an empty list means nothing is indexed there, and has_embeddings: false means word-only matching. These are useful context not available from the schema or annotation. It doesn't contradict the annotation.

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

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

The description is three sentences with no filler, front-loaded with the core purpose, followed by usage guidance and then caveats. Every sentence earns its place with distinct value.

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

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

For a zero-parameter list tool with no output schema, the description covers the essential return information (repo identifier and storage location), the meaning of empty results, and the interpretation of a key row field. It leaves a few details implicit (e.g., what has_embeddings: true means), but the description is adequate for this context.

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

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

The tool has zero parameters and the schema coverage is 100%, so the baseline is 4. No parameter explanation is needed, and the description doesn't need to compensate for undocumented inputs.

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

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

The description opens with a specific verb and resource: 'List every indexed documentation repo with its identifier and storage location.' It explicitly frames the tool as the entry point for obtaining the repo id needed by other tools, distinguishing it from sibling tools without opening their 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 clear contextual guidance: 'Call it first to find out whether the docs you need are already indexed, and to get the repo id every other tool needs.' This is explicit about when to use it, though it does not mention alternatives or exclusions. A 4 fits 'clear context, no exclusions' rather than the full 5.

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

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

Annotations provide readOnlyHint: true, and the description reinforces this by stating 'Read-only: never creates, refreshes, or deletes an index.' It also discloses O(1)-sized response, exact-match precedence, duplicate handling with candidate limit, and relative path resolution.

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 moderately concise with three informative sentences. It is front-loaded with the main action and maintains efficiency, though slightly verbose for its purpose but each sentence adds value.

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

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

Given only one parameter, no output schema, and comprehensive annotations, the description covers matching logic, edge cases (duplicates, no match), O(1) response, read-only trait, and path resolution. It is complete for the tool's complexity.

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 describes the path parameter, and the description adds extra semantics: 'absolute preferred' and resolution behavior against server CWD with _meta.resolved_path. This adds 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 explicitly states the verb 'Resolve' and the resource: a filesystem path to its indexed documentation repo handle. It distinguishes from sibling tools by recommending use instead of doc_list_repos when path is known.

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 when-to-use guidance: 'use instead of doc_list_repos when the path is known.' It also explains matching logic, conditions for no match (GitHub-indexed corpora), and duplication handling.

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

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

Annotations declare readOnlyHint=false, and the description adds rich behavioral details: deterministic assembly, validation of evidence_refs against session-retrieved data (fails closed), session-scoped persistence, return of receipt, immutable resource, appendices once, no character limit, no corpus writes. 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?

Description is detailed but each sentence adds necessary information. Well-structured with purpose first, then behavior details. Slightly long but not verbose.

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

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

Given the tool's complexity and lack of output schema, description fully explains inputs, behavior, validation, failure mode, persistence, and output format. Complete for an AI agent to use 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 good descriptions. Description adds value by explaining caller authors sections, server only assembles, and evidence_refs validation. Adds context beyond 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?

Clearly states the tool finalizes a Markdown handoff for a completed documentation audit/analysis, with specific verb and resource. Distinguishes from sibling tools which are all read-oriented or different operations (search, index, etc.).

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

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

Explicitly says 'for a completed documentation audit/analysis', providing context. Does not explicitly contrast with alternatives, but the sibling tools are clearly different (read/search tools), making usage clear.

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

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

Annotations already declare readOnlyHint=true. The description adds behavioral details: the search algorithm (BM25), filtering before scoring, and return fields. It discloses the INDEX_VERSION dependency, which is beyond what annotations 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?

The description is concise with three sentences: purpose and return fields in the first, optional filters and scope in the second, and usage context in the third. It is front-loaded and every sentence adds value without redundancy.

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

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

Given the complexity (6 parameters, no output schema), the description covers purpose, return fields, optional filters, and preconditions. It references sibling contract for clarity. It does not explain default max_results or provide examples, but those are covered in the schema.

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

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

Schema description coverage is 83%, so the schema already documents most parameters. The description adds minimal meaning beyond the schema, except mentioning that filters are applied before scoring and referencing the search_sections contract for scope filters. This adds some value but not enough to raise the score above baseline.

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

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

The description clearly states the tool searches fenced code blocks using BM25, lists return fields, and distinguishes from sibling 'search_sections' by focusing on code blocks. It is specific about the resource and operation.

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 prerequisites (use after index_local, requires INDEX_VERSION>=3) and mentions optional lang and scope filters. It references the same contract as search_sections, giving implicit guidance on when to use this vs. alternatives, though no explicit when-not-to-use.

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

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

Annotations already indicate readOnlyHint=true. Description adds value by disclosing filter combination (AND'd), return fields format, and the indexing prerequisite, which are useful behavioral details beyond the annotation.

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

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

Four focused sentences with no redundancy: purpose, filter logic, return fields, and prerequisite. Front-loaded and efficient.

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

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

Given no output schema and 4 parameters, the description covers tool purpose, input filtering, output structure, and a critical prerequisite. It provides sufficient context for correct invocation without gaps.

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

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

Description adds meaning beyond schema: path is fnmatch glob and case-sensitive, method is case-insensitive, tag is exact match, and filters are AND'd. This enriches understanding, though the repo parameter lacks extra detail.

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?

Description clearly states verb 'Find', resource 'OpenAPI operations', and filters (path glob, method, tag). It distinguishes itself from siblings like 'find_operations_using_schema' and 'list_endpoints_by_tag' by emphasizing combined filtering.

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 a prerequisite (v1.18+ indexing) but does not explicitly compare with alternatives or state when not to use. Usage context is implied but not fully spelled out.

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, the annotation already covers safety. The description adds useful behavioral detail beyond that: each row includes a referenced_in list and reference resolution is limited to the indexed OpenAPI document. This gives the agent insight into the tool's dependency-cluster behavior and its scope limitation.

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, no filler, and the primary action is front-loaded. Every clause adds meaning: what the tool returns, what each row includes, and the scope limitation.

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

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

For a simple read-only query tool with two parameters and no output schema, the description explains the core return shape (referenced_in list) and the applicable scope. It does not describe pagination or error cases, but those are not essential for a tool of this simplicity.

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

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

Schema description coverage is 0%, so the description carries the full burden. It clarifies schema_name as 'the given schema' and hints that repo refers to the indexed OpenAPI document, but it never explicitly defines repo or its expected format. The two parameter names are somewhat self-explanatory, but the lack of direct parameter descriptions is a noticeable gap.

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

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

The description uses a specific verb and resource: 'Return every operation whose request body or any response references the given schema.' This clearly distinguishes the tool from sibling tools like get_schema_graph or find_endpoint by focusing on operations that use a schema and by noting the referenced_in dependency list.

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 implicit context through 'inside the indexed OpenAPI document only,' which sets a scope boundary. However, it does not explicitly state when to use this tool over alternatives such as get_schema_graph or find_endpoint, nor does it provide 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?

With annotations only providing readOnlyHint, the description carries the full behavioral burden and does so well. It discloses the fusion of embedding and lexical signals, the clustering algorithm, the ranking criteria, verdict tiers, and the important invariant that title_only comparisons are never near_duplicate. The explicit 'Read-only' statement matches the annotation without contradiction.

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

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

The description is dense but every clause earns its place: purpose, method, clustering, ranking, verdicts, and signal semantics. It is front-loaded with the core function and avoids fluff, despite covering a complex tool in only a few sentences.

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

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

Given the tool's complexity and no output schema, the description does an unusually good job of explaining behavior and resulting annotations. It lacks a precise return-shape specification and any prerequisites such as whether the repo must already be indexed, but the core invocation behavior is sufficiently clear for an agent to use 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 several parameters and defaults, but the description adds conceptual meaning to the thresholds by explaining what the fused score is and how near_duplicate_threshold is used. It does not explicitly map max_clusters or exclude_same_doc to the clustering behavior, but the algorithmic context helps an agent reason about these 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 clearly states it performs multi-signal section dedup detection, and goes further to describe the exact method: embeddings plus lexical Jaccard, clustering, ranking, and verdict tiers. This distinguishes it from siblings like search_sections or get_section_diff without requiring schema inspection.

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

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

The intended use is implied: use this when you need to find duplicate or overlapping sections in a repo. However, it does not explicitly contrast itself with alternatives such as search_sections or get_section_diff, nor does it state when not to use it. Guidance is implicit rather than explicit.

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

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

Annotations already declare readOnlyHint=true, indicating safe read-only behavior. The description adds valuable context: sections without metadata.role are bucketed under 'unknown', and results include per-role counts and sample IDs. This goes beyond what annotations provide, though it does not mention rate limits or pagination.

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

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

The description is concise with four short sentences, each adding essential information: action + version, companion reference, unknown bucket behavior, and use case. It is front-loaded with the main action and avoids any fluff.

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

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

Given no output schema, the description adequately explains the return contents (counts, samples, unknown bucket) and purpose (query construction). The parameters are well-documented in the schema. It does not discuss error handling or pagination, but for a simple listing tool this is sufficient.

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 context about the output (counts, samples) which indirectly relates to the sample_size parameter. It does not repeat schema details but adds value by explaining the role discovery use case. No contradictions or misalignments.

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 action: 'list every distinct role classification across the repo with per-role section counts and id samples'. It specifies the resource (roles), scope (across the repo), and additional details (counts, samples). It also distinguishes itself from a companion tool (get_all_tags), ensuring no confusion with siblings.

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

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

The description explicitly says 'Use to discover what roles exist before constructing a role= or profile= query', providing a clear use case. It also references a companion tool (get_all_tags), hinting at a sibling relationship. However, it does not list alternative tools or explicitly state when not to use it.

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

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

Annotations already declare readOnlyHint=true, and the description adds valuable behavioral context beyond that: lowercase normalization and the fact that the tags come from the earlier-stored index, so recent tags may be missing. This gives the agent a realistic sense of staleness and data shape, though return format details are limited.

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 and every sentence earns its place: purpose, companion/usage context, and key behavioral caveats. It is front-loaded and free of fluff.

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

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

For a simple read-only listing tool with only two parameters (both fully documented in the schema), the description covers what it does, which sibling it pairs with, important normalization behavior, and how current the aggregation is. This is sufficient for an agent to decide whether to use the 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%; the repo and min_section_count parameters are already described in the schema. The tool description adds nothing meaningfully new about the params themselves, so the baseline score 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 opens with 'list every unique #hashtag across the repo with per-tag section counts', which clearly identifies the action and resource. It distinguishes itself from sibling tools like search_sections by framing itself as a discovery/listing tool for tag namespaces.

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 positions itself as a 'Companion to the v1.45 tags filter on search_sections' and instructs the agent to 'use this to discover what tag namespaces exist before constructing a tag-filtered query'. This is direct when-to-use guidance with a sibling alternative named.

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

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

Annotations already declare readOnlyHint=true, and the description adds meaningful context beyond that: it specifies the output shape, notes the inverse-reference nature, and discloses the limitation 'Counts links found inside indexed docs only.' No contradictions with annotations.

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

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

Three sentences, front-loaded with the core action, followed by a use case and output format. Every sentence adds value with no redundancy or filler.

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

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

For a simple read-only tool with two well-documented parameters and no output schema, the description provides the essential context: what it returns, why it is useful, and its indexing limitation. It is complete enough for an agent to select and invoke correctly.

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

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

Schema description coverage is 100%, so the schema already documents both parameters (repo and doc_path). The description does not add extra parameter-level detail, but it does clarify the output and scope, which is sufficient given full schema coverage.

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?

Description opens with a specific verb and resource: 'Find all sections that link TO a given document (inverse reference graph).' This clearly distinguishes it from sibling tools like get_related_sections or get_section_blast_radius by focusing on incoming references to a specific document.

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 a concrete use case: 'when a source changes, find which wiki pages reference it.' This gives clear context for when to use the tool, though it does not explicitly mention when not to use it or name alternative tools.

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

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

The description goes well beyond the readOnlyHint annotation by disclosing the exact scope (internal cross-references), the specific syntaxes checked, the exclusion of external links, and the output shape with possible reason values. This gives the agent an accurate mental model of behavior without needing to inspect code.

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

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

The description is two sentences, front-loaded with the main purpose, and every sentence adds value. The second sentence packs in technical details (link types, external skip, output format) without fluff.

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 a single parameter and no output schema, the description fully covers what to expect: input, processing scope, exclusions, output structure, and possible reasons. It is self-sufficient for an agent to invoke and interpret results.

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

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

The schema has 100% coverage for the single 'repo' parameter, so the description need not repeat its meaning. The description does not add any extra semantics about parameter usage beyond what the schema provides, which is acceptable given the high coverage.

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 scans indexed doc files for internal cross-references that no longer resolve, with a specific verb ('Scan') and resource ('indexed doc files'). It also details exactly which link types are checked (markdown, RST directives, anchor-only) and which are skipped (external), making it easily distinguishable from siblings like get_backlinks or get_orphan_sections.

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 to use the tool (to find broken internal links) and explicitly excludes external links, implying it is not for link validation of http/https URLs. However, it does not name alternative tools for such cases, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true; the description adds version requirement (v1.58+) and specifies return fields. It does not contradict annotations and provides useful behavioral context beyond the structural 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?

Two concise sentences with no fluff. First sentence orients with version and pairing, second lists returned fields. Every word earns its place.

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

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

Given the absence of output schema, the description adequately lists return fields and notes limitations (no content). It is complete for its purpose, though could mention error cases or prerequisites for the doc existence.

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

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

Both parameters are fully described in the schema (100% coverage). The description does not add additional semantic value for the parameters beyond what the schema provides.

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

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

The description clearly states 'single-doc detail view' and lists specific return fields, differentiating it from sibling 'list_docs' which is for cross-doc inventory.

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 pairs with 'list_docs' and notes 'No content reads', providing context for when to use. However, it does not mention alternatives for other sibling tools like 'get_section'.

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

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

Annotations already declare readOnlyHint=true, so the description carries less burden. It adds behavioral details: the cap of 200 symbol_ids and the output format {documented, undocumented, coverage_pct}. No contradictions with annotations.

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

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

Two sentences with no fluff. The first sentence states the core purpose, the second adds critical constraints (cap, output format). Information is front-loaded and 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 no output schema, the description provides the output structure, which is helpful. Parameters are fully covered in schema. The tool is simple and the description covers the main functionality. Missing error handling or edge cases but adequate for a straightforward check 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 baseline is 3. The description adds minimal extra meaning beyond the schema; it explains that symbol_ids are used for coverage check but does not elaborate on repo parameter constraints or formats. No additional semantics.

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

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

The description clearly states the verb 'Check' and the resource 'jcodemunch symbols... in this doc index'. It specifies the action: given symbol IDs, reports documented vs undocumented. The output format is provided, and the cap at 200 adds precision. The tool's purpose is distinct from siblings like list_docs or get_undocumented_symbols, though not explicitly differentiated.

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

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

The description implies usage for checking documentation coverage but does not explicitly state when to use or not use this tool versus alternatives. The mention 'Bridges jcodemunch <-> jdocmunch' provides context but lacks clear guidance on exclusions or alternative 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?

With readOnlyHint=true already in annotations, the description adds value by enumerating the diagnostic dimensions (BM25 corpus sanity, embedding coverage, drift status) and clarifying scope. The semantic caveat that index health is orthogonal to content correctness is genuinely useful behavioral context. It doesn't cover cost or error behavior of a potentially expensive aggregate query, but is strong for a read-only tool with good annotations. No contradiction with annotations.

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

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

Exactly three sentences, purpose-first front-loading, each sentence earns its place. The long list of return fields is justified and enumerates scope. Ends with a distinct value-add caveat. No repetition of the tool name or fluff.

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

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

For a single-parameter, read-only tool with no output schema, the description covers the diagnostic scope and its semantic limits quite thoroughly. The only gap is the relationship between `repo` and 'index'—readers must infer that the repo contains the index being diagnosed. A clarification of what the tool returns for invalid/missing repos would round it out.

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

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

Schema description coverage is 0% and the description provides zero explanation of the `repo` parameter, which must have compensated for this gap. The description consistently uses 'index' while the parameter is `repo`, possibly implying the mapping (repo's index) but leaving it to inference. With a single parameter and no documentation, this is a meaningful gap in an otherwise clear description.

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

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

The phrase 'One-shot index health diagnostics' combined with a concrete list of returns (section_count, doc_count, role_distribution, drift status, etc.) makes the tool's purpose specific and concrete. The disclaimer 'Diagnoses the index, not the writing' differentiates it from content-quality analysis, helping to distinguish from similar-sounding siblings like doc_health_radar. However, the verb is nominalized ('diagnostics' rather than an action) and no sibling is explicitly named, so it slightly misses a perfect score.

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?

'One-shot' signals this is a single-call comprehensive health check, giving the agent a clear sense of when to use it. The caveat 'a healthy report says nothing about whether the docs are correct' provides a helpful when-not-to-rely-on-it boundary. However, no alternative tools are named, and there is no explicit 'use X for content quality' pointer despite ~80 siblings existing.

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

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

The description adds significant behavioral context beyond the readOnlyHint annotation, detailing the fused signals (volume, blast_radius, etc.) and the exact output (risk_score, risk_level, top-5 blockers, recommended_action). No contradiction.

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

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

The description is three concise sentences: purpose, input source, and relation to another tool. Every sentence adds value with no redundancy.

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

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

Given no output schema, the description adequately describes the output structure. It also explains input derivation and distinguishes from many sibling tools, providing a complete picture for an agent.

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

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

The description adds critical guidance for the changed_sections parameter, explaining it comes from a git diff or get_recent_changes. With 50% schema coverage, this compensates well, though repo lacks additional semantic context.

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 computes a 'Composite doc-PR risk profile' by fusing specific signals. It distinguishes from siblings by noting it mirrors 'jcm's get_pr_risk_profile' and requires a caller-supplied change list.

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 tells the agent to compute the change list via git diff or use with get_recent_changes. It provides clear context for input preparation but does not explicitly state when not to use the tool or list 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 declare readOnlyHint=true, so the description doesn't need to restate that. It adds behavioral context by stating the tool returns only headings (no content), which is beyond the schema. However, it doesn't disclose details like whether the hierarchy is nested by level, what the return structure looks like, or if it follows a specific document format, which the agent might need to infer.

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 short sentences: it states what it does, what it returns (headings only), and points to the alternative for content. Every sentence earns its place, no fluff.

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

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

For a simple read-only tool with two parameters and no output schema, the description is mostly adequate. However, with no output schema, the agent doesn't know the structure of the returned hierarchy (e.g., whether it's a tree or flat list, if it includes nesting levels). Since the description is the only source of return information, a bit more detail would be helpful, but the core purpose is clear.

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

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

Schema description coverage is 100%, so both parameters (repo and doc_path) are described in the schema. The description adds no additional parameter semantics beyond what's in the schema, which is acceptable per the baseline. It doesn't clarify repo format or doc_path specifics, but the schema is sufficient.

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 retrieves the section hierarchy for a single document file without content, using specific verbs ('Get the section hierarchy') and resource ('single document file'). It also distinguishes from content-fetching tools by explicitly noting 'Headings only, no content' and directs users to get_section for content.

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

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

The description clearly indicates when to use it (to get structure without content) and provides an alternative tool (get_section) for reading content. It does not explicitly state when not to use it, but the differentiation is clear. It could mention using get_toc or get_toc_tree for table-of-contents views, but the core usage context is well-defined.

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

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

The annotations already declare readOnlyHint=true, but the description adds valuable context: counts come from the index and may be stale, and the tool aggregates data from multiple earlier versions. This goes beyond the annotation and helps the agent set expectations about data freshness. No contradiction with annotations.

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

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

The description is two sentences: the first lists all outputs and the second gives the use case and a caveat. It is front-loaded and every clause earns its place. No redundant or filler content.

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

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

For a read-only snapshot tool with a simple 2-parameter schema, the description covers its purpose, returns the fields, the use case, and the data freshness caveat. There is no output schema, so the explicit list of fields is sufficient. The context is complete.

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

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

Schema coverage is 100%, so the description does not need to elaborate on parameters. It mentions the top_tags/top_roles outputs which relate to top_n, but the schema already documents top_n's behavior (default, minimum, and semantics). The description adds no additional parameter meaning, 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 clearly states what the tool does: a single-call repo snapshot listing specific aggregations. It also provides a concrete use case ('what is this repo at a glance?') and distinguishes itself by being a composition of earlier aggregations. The verb 'snapshot' plus the enumerated fields makes the purpose 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 says 'Use for "what is this repo at a glance?"' which is a clear when-to-use statement. It also warns that counts are only as fresh as the last index run, implying not for real-time queries. However, it does not explicitly name alternatives or when-not-to-use, 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?

Beyond the readOnlyHint annotation, the description adds critical behavioral detail: inbound links are counted only across indexed docs, so external links do not rescue a section. It also notes that include_same_doc defaults to false, affecting the count. This goes beyond the simple read-only flag and informs the agent of edge-case behavior.

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

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

The description is concise at two sentences, front-loads the purpose, and provides all necessary context without any filler. Each clause adds value, covering version, definition, sibling relationships, and counting scope.

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

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

Given the tool's simplicity (2 params, no output schema), the description fully covers the purpose, behavior, and scope. It addresses edge cases (external links, intra-doc links) and clearly states the counting logic, making it complete for an agent to use 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% for both parameters, providing clear descriptions of 'repo' and 'include_same_doc'. The tool description does not add much parameter-specific detail beyond what the schema already offers, only reiterating the default behavior of include_same_doc in context. The baseline of 3 applies, as the schema carries the parameter documentation burden.

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 ('list') and a precise resource: sections with zero inbound references from other docs. It also distinguishes itself from sibling tools (get_broken_links, get_stale_pages) by defining exactly what it returns, ensuring the agent understands its unique 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 provides clear context on when to use this tool by framing it as a companion to get_broken_links and get_stale_pages, and clarifies that it finds documentation that exists but nobody links to. It also explains the counting scope (indexed docs only), though it does not explicitly state when not to use it beyond the sibling distinctions.

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; description adds that it's handle-only with no content reads, and mentions _meta.drift_layer reporting.

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

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

Three dense sentences, each adding unique value; 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?

Complete for a read-only diagnostic tool; covers purpose, parameters, and output context without needing output schema.

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

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

Adds meaning beyond schema: explains default cached mirror behavior, live_source fallback, and bucket concepts for boolean 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?

Clearly states it lists sections that have drifted from index state, with specific verb and resource. Distinguishes from sibling tools that handle sections differently.

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 positions as a pre-flight check before re-indexing, explains default behavior vs live_source option.

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?

readOnlyHint=true already declares the safe-read profile, so the bar is lower. The description adds value by disclosing the return composition (structural kinds, cosine-scored semantic neighbors, min_score threshold), but it omits pagination, ordering, and behavior of max_per_kind, and there is no output schema to fill the gap.

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

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

Three dense sentences, front-loaded with the purpose before the returned-content detail, and the mode line reads as a compact quick-reference. No filler, though the terse jargon ('top-N cosine', 'optional cousins') assumes domain familiarity.

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

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

With no output schema, the description is the only source for return shape, and it only sketches the neighbor kinds at a high level. It also never covers the undocumented max_per_kind parameter or result limits, so an agent lacks full behavioral context for a 6-param tool.

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

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

Schema coverage is only 17% (just section_id), so the description must compensate. It does explain mode, top_n (top-N cosine), and min_score (score >= min_score), which adds real meaning. But repo and max_per_kind are left entirely unexplained, leaving half the parameters undocumented anywhere.

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

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

States a specific verb+resource: returns a 'related-section graph' of structural neighbors (siblings, children, parent, cousins) and semantic neighbors. This is concrete and differentiated from generic reads. However, it does not distinguish itself from close siblings like section_neighbors or find_similar_sections, leaving overlap ambiguous.

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

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

No when-to-use guidance is given: nothing tells the agent whether to prefer this over section_neighbors, get_section_context, or find_similar_sections, nor how to choose between structural/semantic/both modes in practice. The mode enum is listed but not framed as a decision rule.

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, indicating idempotency. The description adds value by specifying the BFS traversal algorithm, max_depth bounding, and the structure of the returned data. This provides sufficient 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?

The description is highly concise, using two sentences to convey purpose, return structure, and key parameter details. Every word adds value, and the most important information is front-loaded.

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

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

Despite the lack of an output schema, the description lists the return fields (root, nodes, edges, unresolved) and their contents (type, properties, etc.). It also explains the max_depth parameter, making the tool's behavior predictable. However, it could briefly mention what 'unresolved' means.

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 has 0% description coverage, so the description must explain all parameters. It only partially explains 'schema_name' (as root) and 'max_depth' (with default). The 'repo' parameter is not mentioned at all, leaving its purpose unclear.

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 action ('BFS walk') and the resource ('schema reference graph from a root schema name'), distinguishing it from other schema-related tools. The return structure is also outlined, leaving no ambiguity about what the tool does.

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 guidance on when to use this tool versus alternatives. There is no mention of prerequisites, when not to use it, or comparison to sibling tools like 'find_operations_using_schema' or 'get_section_descendants'.

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

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

Annotations only declare readOnlyHint; the description adds real context beyond that: partial-read semantics (own bytes only, children excluded), and the OCR caveat that text_source='ocr' content may contain errors and scrambled tables/forms. It doesn't cover error behavior or size/truncation limits.

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

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

Three short sentences, front-loaded with the core action, then the ID-discovery prerequisite, then the child-exclusion rule and OCR caveat — every sentence carries distinct information.

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

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

With no output schema, the description adequately covers scope, prerequisites, and a return-quality caveat (OCR). Minor gap: no mention of response size limits or behavior on missing/invalid section_id, which matter for a byte-range fetch.

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 verify, compress_code, strip_boilerplate and section_id are fully documented in the schema. The description adds only the OCR/text_source hint and no additional parameter guidance, so 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 specific verb and resource ('Retrieve the full content of a specific section') and adds mechanism ('byte-range reads'), plus scoping ('Returns this section's own bytes; nested child sections are not included'), which distinguishes it from get_section_descendants/get_sections.

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

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

Explicitly gives the prerequisite flow: 'Use after identifying section IDs via search_sections or get_toc.' Scope exclusion of child sections further implies when to pick a different tool, though no sibling is named directly as an alternative.

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?

readOnlyHint=true is already declared, so the safety profile is covered; the description still adds real context by describing the traversal (BFS over inbound references to max_depth, default 3), the classification of hits (anchor/doc/tutorial), and the returned artifacts (direct_impact, transitive_impact, summary, normalised blast_score in [0,1]). It stops short of stating cost/performance characteristics of a deep traversal.

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

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

Three tight sentences with the core action front-loaded, followed by mechanism, then return shape. Dense but every clause carries information; 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 no output schema, the description compensates by enumerating the returned fields (direct_impact, transitive_impact, summary, blast_score range). Combined with the readOnly annotation and a well-documented input schema, an agent has enough to call it correctly; only traversal cost/limits are unaddressed.

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

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

Schema coverage is 67%, and the schema itself already documents max_depth's default and the section_id format/ambiguity behavior in detail. The description's mention of max_depth (default 3) largely repeats the schema, adding little new meaning beyond framing it as BFS depth over the inbound graph. Baseline 3 for a schema that carries most of 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 operation (transitive impact of rewriting/restructuring a section) and the mechanism (walking the inbound reference graph). It explicitly distinguishes itself from the sibling get_backlinks, which is depth 1 only, so an agent can route between them without opening either schema.

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

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

It clearly frames usage by contrasting with get_backlinks ('Companion to get_backlinks (which is depth 1 only)'), implying this is the multi-depth option. However, it never states when NOT to use it or what other sibling tools (e.g. check_section_delete_safe, get_section_diff) cover, so there is no explicit 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?

readOnlyHint=true already establishes a safe read, so the bar is lower. The description adds useful behavioral context by disclosing exactly what the response is composed of (ancestor chain root→parent, target content, immediate child summaries) and the motivation for the composite. It omits any mention of token-budget behavior or the ambiguity-handling signal, which the schema covers.

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 tightly packed sentences, front-loaded with the return composition and finishing with the motivating rationale. No filler; every clause carries information.

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

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

There is no output schema, so the description rightly explains the return structure (ancestors, target content, child summaries). For a six-parameter read tool with rich schema documentation and a readOnly annotation, this is largely complete, with only minor gaps around token-budget and ambiguity behavior that the schema already handles.

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 fully documents all six parameters (max_tokens budget, include_related, include_children, strip_boilerplate, etc.). The description adds conceptual framing (child summaries, ancestor orientation) but no parameter syntax or default meaning beyond what the schema already states, matching the baseline 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?

States a specific verb (retrieve) and resource (a section) plus the distinctive composite payload: ancestor headings, target content, and child summaries. This clearly differentiates it from plain get_section or get_section_summary by describing what extra context is bundled, though it does not name a sibling explicitly.

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

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

The phrase "Prevents 'section too thin' without falling back to whole-file reads" implies when to prefer this over a whole-file read (get_doc), which counts as implied usage guidance. However, it gives no explicit when-to-use/when-not framing or names the section-level alternatives (get_section, get_section_descendants) an agent should weigh against it.

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

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

Annotations only declare readOnlyHint=true, so the description carries real informational weight: traversal is BFS over parent_id, results are in document order, and each result carries a depth offset — non-obvious behaviors. The 'no content' exclusion also sets expectations. It omits any note about result-size limits for very large subtrees.

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 tightly packed sentences with the core action front-loaded; each clause adds signal. The leading 'v1.43+ —' version tag is minor noise that delays the verb slightly.

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

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

With no output schema, the description must carry the return-value burden; it does describe ordering and depth offset but not the shape of the returned entries or any cap on result volume for deep subtrees. Adequate for a read-only traversal tool, but key return details are left unspecified.

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

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

Schema description coverage is 100%, so repo, section_id and max_depth are already documented; the description's restatement of max_depth=1 adds no meaning beyond the schema. It also does not mention the v1.147+ doc.md#anchor ambiguity fields detailed in the schema. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb+resource (return every descendant of a section) plus the mechanism (BFS over parent_id), ordering (document order) and output attribute (depth offset). It explicitly distinguishes itself from the sibling get_section_path, which returns ancestors, so an agent can route without opening either schema.

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

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

It names the complementary tool (get_section_path for ancestors) and explains the max_depth switch (1 = immediate children only), giving clear selection context. It stops short of explicit when-not-to-use guidance, though 'Handles only — no content' implicitly steers content retrieval to get_section/get_section_excerpts.

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

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

Beyond the readOnlyHint annotation, the description discloses the actual return contents (hashes and diff text) and the sync signal (identical=true). It could go further, e.g. size limits or behavior on a missing section, but it adds real context the annotation does not.

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, no filler, with the core operation front-loaded and the return semantics packed into a dense second sentence.

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 two-parameter read-only tool with no output schema, the description covers the return shape and the key state flag, which is the essential information. It stops short of edge cases such as oversized diffs or missing on-disk files.

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 50% and the description adds no parameter guidance at all, neither for section_id's anchor-reference grammar nor for repo. The rich anchor detail lives in the schema, so the description neither compensates for the undocumented repo param nor repeats what is already covered.

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

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

States a specific verb and resource: a unified diff between the indexed snapshot and the current on-disk bytes for a section. It clearly separates itself from get_section (extraction) and check_section_delete_safe (safety), though it never names a sibling explicitly.

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

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

Usage is implied rather than stated: the 'identical=true when in sync' clause hints at a staleness-check use case, but there is no explicit when-to-use, when-not-to-use, or named alternative such as get_recent_changes or get_stale_pages.

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

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

With readOnlyHint=true already declaring a safe read, the description adds genuine behavior: the excerpt is trimmed to the last newline before the byte cap so it ends on a paragraph boundary, and _meta.tokens_saved reports byte-savings. It doesn't say what happens when a section is smaller than the cap, but the added context 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?

Three tight sentences with no filler; the version gate and the core purpose are front-loaded, and the trimming rule and savings metric follow immediately.

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

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

No output schema exists, so the description carries the return-value burden — it names the excerpt content and the _meta.tokens_saved field, which is enough for an agent to use the result. Minor gaps (e.g. behavior for very short sections) remain.

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

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

Schema coverage is 100%, so repo, max_bytes, and section_id are already documented, including the anchor reference format. The description only restates the 500-byte default and adds the newline-trimming semantics, which is marginal beyond the schema — baseline 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?

States a specific verb and resource — return a short content preview for one section — with the default size (500 bytes) and trimming rule. It is clearly distinguishable from get_section (full read) and the plural get_section_excerpts 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?

Explicitly tells the agent to use it to peek at content before paying for a full get_section read, naming the alternative and the cost tradeoff. It lacks guidance on when to prefer get_section_excerpts (bulk) instead, so it stops short of full routing coverage.

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 carry readOnlyHint=true, so the description must add the rest, and it does: single index load efficiency, per-id error reporting in-line, _meta.tokens_saved aggregation, and intentional truncation. This goes well beyond the safety hint, though it omits any pagination/limit behavior for very large batches.

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 identity ('batch counterpart to get_section_excerpt') then the key behavioral facts in terse sentences. The version tags (v1.49+) are mild noise, but overall it is efficient and well-ordered.

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

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

With no output schema and no destructive/param annotations to lean on, the description still conveys return-relevant behavior (_meta.tokens_saved, per-id errors) and truncation semantics, making it callable without opening anything else. Only minor gaps remain (batch size 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 description coverage is 100%, so repo, max_bytes, and section_ids are already documented (including the doc.md#anchor behavior). The description adds no parameter-level detail beyond what the schema provides, 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 specific verb+resource (resolves batch section excerpts) and explicitly distinguishes itself from siblings: it is the 'batch counterpart to get_section_excerpt' and points to get_sections for full content. An agent can differentiate it from get_section_excerpt, get_sections, and get_section_summaries by the batch/preview framing alone.

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

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

Clearly routes the agent: use this for N previews in one call, and use get_sections for full content ('Previews are truncated by design; read full content with get_sections'). It names the alternative and the condition, though it doesn't spell out the when-not relative to get_section_excerpt beyond the batch framing.

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

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

With readOnlyHint=true already declaring the safety profile, the description adds genuine behavioral context beyond annotations: the upward parent_id traversal, cycle protection, and the exact per-step payload ({id, title, level, doc_path}) plus depth. This tells the agent what the result looks like without needing an output schema.

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

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

Tight and front-loaded: version tag, core behavior, then return shape. Every clause earns its place, though the leading 'v1.40+' and the slightly clipped 'Handles only (...)' phrasing are marginally less readable than ideal.

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

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

No output schema exists, and the description compensates by describing the return shape (breadcrumb chain, per-step fields, depth) and traversal semantics. For a two-parameter read tool this is essentially complete; only edge-case behavior (e.g. what happens when a section has no parent) is left implicit.

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

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

Schema description coverage is 100%, so both parameters are fully documented in the schema (including the v1.147+ anchor handling and ambiguity fields). The description adds no parameter meaning beyond what the schema already provides, 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 specific verb+resource: returns the breadcrumb chain (root → ... → target) for a section_id. An agent can tell it produces an ancestry path, distinct from sibling tools like get_section_descendants. It stops short of naming the sibling it differs from, so 4 rather than 5.

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

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

The description explains the mechanics ('Walks parent_id upward') but gives no when-to-use guidance, no alternatives (e.g. get_section_context, get_toc), and no conditions that select this tool over its many section-oriented siblings. Usage is only implied by the purpose.

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

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

Annotations only declare readOnlyHint=true, so the description carries the rest. It adds meaningful behavior beyond that: partial-failure semantics (unknown ids yield per-id errors rather than failing the whole call) and the fact that only requested ids return content. Return payload format is left unspecified, but the error contract is genuinely useful.

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

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

Two tight sentences, zero waste, with the batch scope front-loaded before the error-handling nuance. 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?

For a read-only batch retrieval with full schema coverage and an annotation covering safety, the description supplies the key operational detail (per-id error behavior). With no output schema present, it could say a bit more about the returned content shape, but nothing essential to correct invocation is missing.

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

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

Schema description coverage is 100%, with detailed per-parameter notes (anchor references, compress_code, strip_boilerplate) already in the schema. The description adds no parameter-level meaning, so the 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?

States a specific verb (batch content retrieval) and resource (sections), and the phrase 'multiple sections in one call' implicitly distinguishes it from the singular get_section sibling. It stops short of naming that sibling explicitly, which is the only thing keeping it from a 5.

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

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

Clearly frames the use case (retrieve content for several sections efficiently in one round trip) and adds a concrete behavioral rule about unknown ids. It doesn't name alternative tools or list when-not-to-use conditions, so it's clear context without explicit routing.

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

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

With readOnlyHint=true already covering the safety profile, the description adds genuinely non-obvious behavior: the batch shares one index load, and per-id failures are surfaced in-line on the result entry instead of aborting the whole call. That error-isolation contract is exactly the kind of detail annotations cannot 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?

Three tight sentences with no filler, and the batch-vs-single distinction lands early. The leading version stamp ('v1.48+ —') occupies the highest-value position with release trivia rather than the tool's purpose, which slightly weakens front-loading.

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, two-parameter tool with no output schema, the description covers purpose, the batch/single routing, and the error-handling contract. The remaining detail (returned fields, anchor edge cases) lives in the schema, so nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% and both parameters (repo, section_ids) are fully documented there, including ordering, requested_id correlation, and the anchor reference handling. The description adds nothing about parameters 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 description gives a specific verb and resource ('Resolve metadata for many ids') and immediately positions the tool against a named sibling ('batch version of get_section_summary'), so an agent can distinguish batch from single lookup without opening either schema.

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

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

It clearly states the usage context: use this when you have many ids and want a single index load, versus the singular get_section_summary. It does not, however, state any exclusion conditions or cost/limit tradeoffs that would tell an agent when NOT to batch.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds genuine behavioral context: it returns metadata 'without fetching content', clarifying this is a lightweight inspection call. It stops short of noting cost/latency traits or whether the summary is cached/version-dependent, keeping it at a 4.

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

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

Two sentences, front-loaded with the return payload and the field list, then the usage directive. The long field enumeration slightly bloats the first sentence and the 'v1.38+' version tag is minor clutter, but nothing is wasted.

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

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

With no output schema, the description compensates by enumerating exactly what fields are returned. Annotations cover safety and the usage sentence covers the decision path. Only a note on return edge cases (e.g., missing sections) is absent, which is minor.

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 parameters (repo, section_id) are fully documented in the schema itself, including the v1.147+ anchor behavior. The description adds no parameter-level meaning beyond pointing back to the section concept, 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 specific verb (return) and resource (full indexed metadata for one section), enumerates the concrete fields returned, and explicitly distinguishes itself from get_section by noting it works 'without fetching content'. An agent can tell it apart from get_section_summaries/describe_section without opening any schema.

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

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

Explicitly prescribes when to use it ('to inspect role/tags before deciding whether to read the content') and names the alternative tool (get_section) with the condition that selects it. The when/when-not framing is complete.

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 already covering safety, the description adds real behavioral context: the savings counter is modeled (file bytes avoided minus bytes served; searches earn none) and the latency ring is volatile, cleared by a server restart. These are non-obvious traits an agent could not derive from the annotations or empty 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?

Three sentences, front-loaded with the return contract before the operational caveats, and every sentence carries information. The inline JSON-ish field list is slightly dense but is the most load-bearing part of the 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?

There is no output schema, so the description correctly carries the return-value burden by naming both fields and explaining how total_tokens_saved is computed. Minor gaps remain (units/format for latency_per_tool, whether the counter is cumulative per session), but for a zero-parameter read tool 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?

The tool takes zero parameters, so the baseline is 4 and there is no schema surface for the description to elaborate on. The description's inline return-shape detail is useful but belongs to output rather than parameter semantics.

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

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

The description opens with a specific verb+resource ('Session self-monitor: returns...') and immediately enumerates the returned fields, so an agent knows exactly what comes back. It explicitly names the sibling it is not (analyze_perf), which removes ambiguity among a large set of stats 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?

It routes windowed analysis to analyze_perf, giving a concrete condition for choosing the alternative. It also flags the tool's lightweight/in-memory nature, though it does not spell out an explicit 'when not to use' beyond the analyze_perf redirect.

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

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

The description discloses that the tool checks source file modifications against last indexed state and lists reasons for staleness. This goes beyond the readOnlyHint annotation by detailing the checking behavior and output structure.

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 long, front-loaded with the primary purpose, explains the convention, and specifies the output. Every sentence adds value with no redundancy.

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

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

Given the tool's complexity (checking file modifications) and the presence of annotations and full schema coverage, the description provides sufficient context including output structure and behavioral expectations.

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 baseline is 3. The description adds no extra meaning beyond what the schema already provides for 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 clearly states the tool's purpose: finding wiki pages whose declared sources have been modified on disk. It explains the YAML convention and lists the output format, distinguishing it from sibling tools that focus on other aspects of wiki pages.

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

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

The description implies when to use the tool (to check for stale sources), but does not explicitly state when not to use it or provide alternatives among siblings. However, the context is clear enough for an agent to decide.

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

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

The readOnlyHint annotation already signals a safe read operation. The description adds useful behavioral detail beyond that: content is excluded, output is flat and sorted by document order, and there is no doc_path parameter. It still does not describe the exact return fields, but for a list-oriented read tool that is a minor gap.

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

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

Two sentences, no filler, and the core purpose is front-loaded. The exclusion and sibling guidance are packed into the same compact paragraph without losing clarity.

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 this tool's complexity, the description is complete: it defines scope, return shape ('flat table of contents'), exclusions, and alternatives. Since no output schema exists, the description adequately tells the agent what to expect without needing to enumerate every field.

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 repo, limit, offset, and path_glob. The description reinforces path_glob scoping and the absence of doc_path, but does not add syntax or format guidance beyond what the schema 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?

States a specific verb and resource: 'Get a flat table of contents for all sections in a repo, sorted by document order.' It also distinguishes the tool from the closest siblings by excluding content and naming get_section and get_document_outline as alternatives.

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 routing: use get_section to retrieve content, use get_document_outline for a single document, and use path_glob to scope the result. It even notes the absence of a doc_path parameter, which prevents misuse.

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?

readOnlyHint=true already tells the agent this is a safe read. The description then adds genuinely useful scope information — 'Content is excluded,' i.e. headings only, no body text — which is not inferable from annotations or schema. It stops short of describing the shape of returned tree nodes, which matters since no output schema 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?

Three short sentences, front-loaded with the core verb and resource, no filler. 'Shows parent/child heading relationships' mildly restates 'nested' from the first sentence, a small redundancy, but the size is well matched to 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?

The read-only nature and content-exclusion are covered, and pagination is fully specified in the schema, but with no output schema the description should say something about the returned tree structure (e.g. node fields such as heading title, depth, or path) so the agent knows what it will parse.

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%, and the parameter docs are unusually rich (version gates, offset/limit semantics, next_offset, the 1 MiB response ceiling with refusal-not-truncation). The description adds nothing 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 specific verb and resource ('Get a nested table of contents tree per document') and adds the structural trait (parent/child heading relationships, content excluded). However, it does not distinguish itself from close siblings like get_toc or get_document_outline, so an agent must still infer which TOC-shaped tool to pick.

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

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

There is no when-to-use guidance and no mention of alternatives such as get_toc or get_document_outline, despite three TOC/outline-style siblings existing. The only usable cue is the implicit scope of 'per document,' which is not framed as a selection condition.

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?

readOnlyHint already establishes the safe-read profile, and the description adds real value beyond it: the three detected conventions, the returned chain[] shape with strategy, and the explicit failure mode that unrecognized wiring yields a short chain. No contradictions.

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

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

Three tightly packed sentences, front-loaded with the action and mechanism, then the return and limitation. Every sentence earns its place with no filler.

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

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

With no output schema, the description usefully specifies the return payload (chain[] of section_id/doc_path/title plus strategy) and the short-chain limitation. The only gap is the undocumented repo parameter, which is minor for this read-only 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 50%: section_id is richly documented (including anchor/ambiguity behavior) while repo has no schema description. The description adds only that section_id is the traversal start point and says nothing about repo, so it neither fully compensates nor is unnecessary.

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 (reconstruct) and resource (ordered tutorial chain) plus the starting point, and enumerates the exact detection strategies. An agent can distinguish this from path/toc siblings like get_section_path or get_toc_tree 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?

Clearly frames when the tool applies: it follows only three conventions and returns a short chain for any other wiring, which tells the agent when results will be incomplete. It stops short of naming alternative tools for non-conventional tutorials, so it is not a 5.

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

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

Annotations indicate readOnlyHint=true, and the description adds 'best-effort' and a note about _meta.bridge_available=false, providing useful behavioral context beyond annotations. However, it lacks details about performance or result limits.

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

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

Two sentences, front-loaded with purpose; concise but the first sentence is slightly dense. Could be slightly clearer about the relationship between parameters.

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

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

With no output schema and sparse parameter documentation, the description does not explain what the output looks like or how to interpret results. The tool's role among many siblings is not fully contextualized.

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 has 0% description coverage; the description mentions 'code_repo' but does not explain all three parameters. The distinction between 'repo' and 'code_repo' is unclear, and 'max_symbols' is not described at all.

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 enumerates symbols in a code_repo and returns those not documented, which is a specific verb-resource pair. It distinguishes from sibling tools like get_doc_coverage by focusing on inverse coverage.

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

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

The description implies usage for finding undocumented symbols, but does not provide explicit when-to-use or when-not-to-use guidance, nor does it compare to alternatives like get_doc_coverage or search_titles.

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

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

Annotations only declare readOnlyHint=true, and the description adds a precise return shape, the local-vs-GitHub distinction, and actionable remediation commands. No contradiction exists, and the added context goes beyond the annotation.

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

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

Three sentences pack an overview, return shape, follow-up commands, and scope limitation without any filler. Each sentence earns its place, and the first sentence front-loads the core purpose.

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 zero parameters and no output schema, the description covers behavior, return shape, scope exclusions, and next steps. The only minor ambiguity is the 'hint' field, but the overall picture is complete enough for an agent to invoke the tool correctly.

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

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

The tool has zero parameters, so the schema already defines everything; the description has nothing to add. The return-object shape described partially compensates for the lack of an output schema, aligning with the baseline for no-parameter 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 'Reports whether' with explicit subjects ('jdocmunch-watch service', per-repo 'source_root exists'), defining a specific status-check resource. This clearly distinguishes it from sibling doc-coverage or section-summary tools.

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

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

The description states the tool's scope ('Covers locally-indexed repos only') and explicitly excludes GitHub-indexed repos, but it does not name a sibling alternative for those cases. It also provides commands to run to maintain freshness, implying the check is used to decide when to act.

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 indicate readOnlyHint=true. The description adds value by detailing the exact return values (orphan pages, top-linked pages, tag distribution, link count, and section stats), which are not specified elsewhere. No contradictions.

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

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

The description consists of just two efficient sentences. The first sentence states the tool's purpose, and the second lists its outputs and usage. No extraneous 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 the lack of an output schema, the description adequately explains the return values. It covers the main statistics but omits potential error conditions or limitations. For a simple one-parameter tool, this is sufficient.

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 has 100% coverage with a single parameter 'repo' described as 'Repository identifier (owner/repo or just repo name).' The description does not add any additional semantic information beyond what the schema provides.

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

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

The description clearly states it's a 'Wiki health dashboard' and enumerates the returned statistics (orphan pages, most-linked pages, tag distribution, etc.), making its purpose specific and distinct from other sibling tools.

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

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

The description advises using it for 'periodic wiki lint checks,' which provides a clear usage context. However, it does not explicitly differentiate from similar health-check tools like get_doc_health or get_broken_links, nor does it state when not to use it.

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

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

Annotations declare only readOnlyHint=false, so the description must carry the behavior, and it does extensively: duplicate/conflict handling, handle reuse, embeddings auto-enable conditions, OCR gating via JDOCMUNCH_OCR, oversize skip reporting, and changes-list capping. This is far beyond what the single annotation conveys.

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, which is good, but the remainder is a single dense mega-paragraph blending parameter detail, output-field semantics (coverage_complete, skip_counts, changes, duplicate_anchors), and version notes. It earns its length somewhat (no output schema exists) but lacks structure, making it hard to scan.

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

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

For a 17-parameter mutation tool with no output schema, the description compensates thoroughly by explaining return semantics: coverage vs truncation, skip_counts, the capped `changes` list with deleted-last ordering, and duplicate_anchors reporting. An agent has enough to call it correctly and interpret results.

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

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

Schema coverage is 100%, so all 17 parameters are already documented in structured fields (including complex ones like legacy_reconcile, worktree_mode, sort_by). The description mostly restates output/truncation semantics rather than adding meaning to individual parameters, so 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 specific verb and resource ('Index a local folder containing documentation files'), names the accepted file types, and implicitly distinguishes itself from retrieval siblings (search_sections, get_section, etc.). An agent knows this is the build/ingestion step, not a query.

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

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

Gives an explicit when-to-use-alternative: for tens of thousands of files that outlast a client timeout, run the `jdocmunch-mcp index-local` CLI instead. Also explains incremental default. Does not, however, explicitly route the agent between this and the sibling `doc_index_repo`, leaving that choice implicit.

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

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

Adds idempotent and no repo context required beyond readOnlyHint annotation. No contradictions.

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

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

Three sentences, each earning its place. Purpose front-loaded, 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?

Comprehensive for a parameterless tool with no output schema. Explains return value and use case fully.

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?

No parameters (schema coverage 100%), baseline 4 for 0 params. Description does not need to add param info.

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 it returns the version-current policy snippet for jdocmunch-mcp, a specific verb+resource. Distinguishes from sibling jcodemunch_guide.

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?

Describes how agents can use it (one-line CLAUDE.md) and why (avoid static drift). Does not explicitly mention when not to use or alternatives, but provides clear context.

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

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

Annotations already mark the tool as read-only (readOnlyHint=true), so the description does not need to state that. It adds value by noting the 'best-effort' nature (non-guaranteed success) and describing the return structure (by_block, by_symbol, _meta with bridge_available). This goes beyond 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: first states purpose, second explains process and return value. It is front-loaded, concise, and every sentence contributes meaning. No redundancy or 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?

Given the tool has 4 parameters (2 required), no output schema, and readOnly annotations, the description provides the essential information: purpose, process, return structure, and a dependency note (jcodemunch-mcp importability). It lacks explicit error handling or performance caveats, but is mostly complete for an agent to invoke correctly.

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

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

Schema description coverage is 50% (2 of 4 parameters have descriptions). The description adds context about the overall process (tokenizing and looking up) but does not elaborate on individual parameters beyond what the schema already provides. For a tool where the parameters are fairly self-explanatory (repo identifiers), this is adequate but not compensatory.

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: 'Best-effort bridge from doc code blocks to jcodemunch code symbols.' It identifies the specific verb (bridge) and resources (doc code blocks, jcodemunch symbols), and it distinguishes itself from siblings because no other sibling performs this linking function.

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 process ('For each block, tokenizes identifiers and looks them up via jcodemunch's search_symbols'), which implies when to use it. However, it does not explicitly state when not to use it or mention alternatives among the sibling tools. The guidance is adequate but lacks exclusionary context.

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