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?

The description adds value beyond the readOnlyHint annotation by disclosing the composite logic and output shape (verdict fields, up to 5 ranked blockers, recommended_action). It also explicitly states 'Read-only — never mutates the index,' reinforcing the 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?

The description is dense but well-structured: the first sentence states purpose and inputs, the second covers output and safety. Every clause earns its place, though the long first sentence could be split for readability.

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

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

Given there is no output schema, the description sufficiently enumerates the verdict fields and mentions ranked blockers and recommended_action. It could elaborate on the meaning of safe_to_delete or the ranking criteria, but for a preflight tool it is reasonably 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 75%, so baseline is 3. The description adds high-level context by naming 'transitive doc-level backlinks' and 'recent-edit recency,' which map to transitive_depth and recent_edit_days, but it does not explicitly tie the parameters to their behavior or provide format details beyond the schema. The repo parameter remains wholly undescribed in both.

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 'Composite preflight: is this section safe to delete?' which is a specific verb+resource with clear scope. It also distinguishes itself from siblings by naming the fused inputs (tutorial-path membership, anchor-specific backlinks, transitive backlinks, recency) and the unique verdict output.

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 term 'preflight' gives clear context: this is to be used before deleting a section. It does not explicitly name alternatives or exclusions, but the composite nature implies it replaces multiple lower-level checks, which is sufficient guidance.

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

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

Annotations only declare 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, and the description adds 'No content reads,' which is consistent and clarifies that no content is fetched. The description also reveals the bundled nature of the data (metadata, breadcrumb, neighbors), providing useful behavioral context beyond annotations. 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 is two sentences, highly concise and front-loaded. The first sentence states the core functionality, and the second adds a benefit and constraint. 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?

Despite no output schema, the description gives a clear picture of what is returned: 'full metadata + ancestor breadcrumb + prev/next/parent/first_child neighbors.' It also includes version context ('v1.54+'). For a tool with only 2 parameters, this is complete and 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%, with both parameters (repo, section_id) described in the input schema. The description does not add additional parameter-level semantics beyond what the schema provides. Per guidelines, with high schema coverage, 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 the tool provides 'full metadata + ancestor breadcrumb + prev/next/parent/first_child neighbors for one section in a single call.' It distinguishes from siblings by explicitly comparing to separate calls (get_section_summary + get_section_path + section_neighbors) and noting 'No content reads.' The verb 'describe' matches the purpose.

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

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

The description gives usage guidance by stating it 'Saves three round-trips vs calling get_section_summary + get_section_path + section_neighbors separately,' implying when to use this tool (when you need all that data) and alternatives (the individual calls). It also mentions 'v1.54+' as a version requirement. However, it does not explicitly state when not to use it or other scenarios.

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?

The description discloses key behavioral traits: it only indexes .md and .txt files, ignores all other files, and auto-enables embeddings when a provider is configured. It also explains the incremental behavior (skips HTTP fetches if commit SHA unchanged). The annotation readOnlyHint=false is consistent with the description's implication of writing to local storage. The description adds value beyond the annotation by detailing the file-type filtering and embedding configuration.

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 and front-loaded with the main purpose. It uses two sentences to convey the core functionality and then adds a third sentence about file-type filtering. It's efficient with no wasted words, though it could be slightly more structured (e.g., bullet points for embedding providers).

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 (6 parameters, embedding configuration, incremental behavior), the description covers the essential aspects: what it does, what files it processes, how embeddings are enabled, and the incremental behavior. It doesn't explain the return value (no output schema), but that's acceptable since the tool likely returns a status or index ID. The description is complete enough for an agent to understand when and how to use it.

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

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

The schema description coverage is 100%, so the schema already documents all parameters. The description adds context about the overall behavior (e.g., 'Indexes .md and .txt only') but doesn't add much per-parameter detail beyond what the schema provides. However, it does clarify the embedding auto-enable logic and the incremental behavior, which are not fully captured in the schema. Given the high schema coverage, a baseline of 3 is appropriate, but the description's additional context on embedding and incremental behavior justifies a 4.

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

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

The description clearly states the tool's purpose: 'Index a GitHub repository's documentation.' It specifies the verb (Index), the resource (GitHub repository's documentation), and the scope (.md/.txt files). It distinguishes from siblings like index_local (which likely indexes local content) and doc_list_repos (which lists repos).

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: to index GitHub repository documentation. It also explains what it does (fetches .md/.txt, parses sections, saves to local storage) and mentions the embedding auto-enable behavior. However, it doesn't explicitly state when NOT to use it or name alternative tools for different scenarios (e.g., if you need to index local files, use index_local).

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 safety, and the description adds meaningful behavioral context: results are limited to the active storage_path, and an empty list is a definitive signal that nothing is indexed there. This goes beyond the annotation without contradicting it.

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

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

Three sentences with no filler: the first states the core action, the second gives usage guidance, and the third clarifies scoping. Every sentence earns its place 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?

For a zero-parameter, read-only listing tool with no output schema, the description is complete: it defines what is returned, how to use the tool as a prerequisite, and how to interpret an empty result. No critical behavioral or return-value information is missing.

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

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

The tool has zero parameters, so the default baseline of 4 applies. The description adds useful output semantics by stating that the repo identifier and storage location are returned, which is sufficient since the schema has no parameters to document.

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: 'List every indexed documentation repo with its identifier and storage location.' It clearly distinguishes the tool as the entry point for discovering indexed repos, which differentiates it from siblings like list_repo_groups or get_index_overview.

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 instructs 'Call it first' to determine whether docs are indexed and to get the repo id needed by other tools. It also notes the storage_path scoping and the meaning of an empty list, though it does not name specific alternative tools or when-not-to-use conditions.

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?

Annotations already declare readOnlyHint=true. The description adds behavioral details: it returns two categories of neighbors, uses cosine similarity, and supports a mode parameter. 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 is extremely concise (two sentences) yet conveys the core functionality, modes, and key parameters without any 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?

For a tool with no output schema, the description covers the main outputs (structural and semantic neighbors) and thresholds. It lacks details on the response format (e.g., whether it returns section IDs or full objects) but is otherwise adequate given the 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 description explains 'mode' (structural/semantic/both), 'top_n' (top-N), and 'min_score' (score threshold). However, 'max_per_kind', 'repo', and 'section_id' are not elaborated. With 0% schema coverage, this partial explanation is helpful but not comprehensive.

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 specifies the tool retrieves structural neighbors (siblings, children, parent, optional cousins) and semantic neighbors (top-N cosine with score threshold). It distinguishes itself from siblings like 'section_neighbors' by explicitly naming modes and neighbor types.

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 (when needing related sections) but provides no explicit guidance on when to use this versus alternatives, nor any exclusions or prerequisites.

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 already provide readOnlyHint=true, so the read-safety is established. The description adds meaningful behavioral context: it mentions byte-range reads and explicitly states that nested child sections are not included, clarifying the return scope beyond what annotations convey.

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

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

Two efficient sentences with no wasted words. The purpose is stated first, then usage guidance, and finally a scope limitation. Every clause 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?

Despite no output schema, the description clearly states what is returned (full content, own bytes, no nested sections). It covers the core behavior and an important boundary. Additional details about optional parameters are handled by the schema, so the description is sufficiently complete for a read tool.

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

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

Schema description coverage is 100%, so parameters are fully documented in the schema itself. The description does not add parameter-specific semantics beyond the schema, but that is acceptable given the schema's thoroughness.

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 (Retrieve the full content of a specific section) and the resource (a specific section). It distinguishes from sibling tools by noting that nested child sections are not included, which separates it from tools like get_section_descendants or 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?

Provides clear usage context by instructing to use after identifying section IDs via search_sections or get_toc. Does not explicitly list alternatives or when-not-to-use, but the prerequisite guidance is specific and sufficient for typical workflows.

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 reveals detailed behavior: BFS traversal, configurable max_depth, classification of hits (anchor/doc/tutorial), and a normalized blast_score. The read-only behavior matches annotations (readOnlyHint=true), and no contradictions are present. The description adds significant 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 three sentences with no wasted words. It front-loads the tool's core action and details the graph walk, outputs, and relation to sibling tools. 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?

For a complex graph-walking tool, the description covers the purpose, mechanism, and return fields. Without an output schema, it adequately lists common return values. Minor gaps include error handling or performance notes, but overall complete for an expert 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 input schema already describes max_depth (default 3) and section_id format. The description adds no additional meaning for the repo parameter and only restates existing info. With 67% schema coverage, the description does not significantly improve parameter understanding.

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 the transitive impact of rewriting a section by walking the inbound reference graph. It lists specific outputs (direct_impact, transitive_impact, summary, blast_score) and differentiates from sibling get_backlinks (depth 1 only), giving a precise purpose.

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

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

The description explicitly mentions when to use this tool over its companion get_backlinks (depth 1 only) and notes it is read-only. It provides clear context, though it does not explicitly state when not to use it or mention other 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 already declare readOnlyHint=true. The description adds that ancestors and child summaries are always included, max_tokens is approximate, and describes optional features (include_related, strip_boilerplate). This goes beyond annotations by detailing what is guaranteed in the response.

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

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

The description is two sentences with no wasted words. It front-loads the core purpose and hierarchy, then adds a clear benefit statement. 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 6 parameters and no output schema, the description covers the tool's input, behavior, and output structure (ancestors, target, children) comprehensively. It explains what each parameter does and what the response includes, leaving no major gaps.

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

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

Schema coverage is 100% with each parameter described. The description adds value by explaining max_tokens as approximate, clarifying that ancestors/children are always included, and providing version context for include_related and strip_boilerplate. This enriches the schema definitions.

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

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

The description clearly states it retrieves a section with its full hierarchy context, including ancestor headings, target content, and immediate child summaries. This distinguishes it from sibling tools like get_section (likely just the section) or get_section_summary (just summary). The phrase 'prevents section too thin' further clarifies 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 explains that the tool is used to avoid 'section too thin' without whole-file reads, implying it provides richer context. However, it does not explicitly name alternatives like get_section or search_titles, though the purpose is clear enough for an agent to infer when to use this tool.

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

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

Annotations already indicate readOnlyHint=true, so the description needs to add behavioral specifics. It does so by clarifying the traversal algorithm (BFS), ordering (document order), depth offset, and the fact that only handles are returned ('Handles only — no content'). 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 with no fluff. It front-loads the version requirement and key operation, then adds details in a logical order. Every sentence adds unique 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 absence of an output schema, the description hints at the return structure (descendants in order, handles only). While it doesn't explicitly state the exact format (e.g., array of section IDs), it provides enough context for an agent to understand the output nature. The tool's complexity (BFS, depth handling) is well-covered.

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 must add extra value. It reiterates max_depth behavior with a concrete example and notes that the section_id target itself is not included (not in schema). This provides clarity beyond the schema descriptions.

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 specifies the verb 'return', the resource 'every descendant of a section', and the method 'BFS over parent_id' with ordering 'in document order with depth offset'. It also pairs with a sibling tool (get_section_path for ancestors), clearly distinguishing its purpose.

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

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

The description explicitly pairs with get_section_path (ancestors), providing a complementary use case. The optional max_depth parameter is explained with a concrete example (max_depth=1 returns immediate children). However, it does not state explicit when-not-to-use scenarios or alternatives beyond the one sibling.

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

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

Annotations show readOnlyHint=true, and the description adds that the tool compares the indexed snapshot to the current on-disk byte range and returns a diff indicating sync status. This provides useful behavioral context beyond the annotation, though it does not detail potential side effects or performance implications.

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 short sentences, front-loading the core purpose and key output details. Every word adds value, with no redundancy or unnecessary information.

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

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

For a tool with no output schema and zero parameter descriptions, the description should explain parameters and possibly expected inputs. It lacks this crucial information, leaving the agent unguided despite adequate behavioral disclosure for the read operation.

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 offers no explanation for the two parameters (repo, section_id). With no compensation, the agent cannot infer what values these parameters expect, severely hindering correct invocation.

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 compares 'indexed snapshot' and 'current on-disk byte range' for a section, returning hashes and diff text, with 'identical=true' when in sync. It specifies the verb (get diff) and resource (section), distinguishing it from related tools like get_section which return metadata or get_section_context.

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

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

No explicit guidance on when to use this tool versus alternatives like get_section or get_section_context. Usage is implied (e.g., to check sync status) but not stated, and no exclusion criteria or prerequisites are provided.

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

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

Annotations already declare readOnlyHint=true. Description adds that the excerpt is 'trimmed to last newline before the cap so it ends on a paragraph boundary' and reports '_meta.tokens_saved', which are important behavioral details not covered by 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?

Description is two sentences plus a metadata note, front-loaded with version and purpose. Every sentence provides essential information 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?

With no output schema, the description adequately explains the return format (short preview, trimmed, with _meta.tokens_saved). Parameter usage is clear, and the tool's purpose is well-contextualized among siblings.

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 parameters are already described. Description adds meaning by explaining the trimming behavior relative to max_bytes and the default value of 500, which goes beyond the schema's description of max_bytes as 'Soft cap on excerpt size'.

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 states 'return a short content preview (default 500 bytes) for one section', which is a specific verb+resource. It distinguishes from sibling 'get_section' by mentioning 'peek at content before paying for a full get_section read'.

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 'Use to peek at content before paying for a full get_section read', providing clear context for when to use. Does not explicitly state when not to use, but the guidance is sufficient.

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 valuable behavioral context: single index load efficiency, per-id error reporting, aggregated byte savings via _meta.tokens_saved, and truncation by design. These enrich the annotation-provided safety profile.

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

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

The description is four concise sentences, front-loaded with purpose, and each sentence adds useful information (batch context, error handling, token savings, truncation). No redundancy 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?

Even without an output schema, the description informs the agent of return structure (previews, inline errors, _meta.tokens_saved) and limitations (truncation). Given the read-only annotation and batch nature, this is complete and 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 input schema already covers 100% of parameters with descriptions (including order preservation and requested_id for correlation). The description does not add additional semantics beyond the schema, so it meets the baseline of 3.

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

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

The description clearly states the tool's action: it resolves N previews in one call, acting as a batch counterpart to get_section_excerpt. It specifies the resource (section previews) and differentiates from the singular variant and get_sections for full 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?

It explicitly positions itself as the batch version, and provides a clear alternative: 'read full content with get_sections.' This tells the agent when to use this tool (batch previews) and when to choose an alternative (full content needing).

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

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

Annotations declare readOnlyHint=true, and the description adds that it walks parent_id upward and is cycle-protected, which are behavioral traits beyond annotations. 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 concise sentences front-loaded with version and core purpose. Every sentence adds value with no waste. Highly structured 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?

Despite no output schema, the description explains what each step returns (id, title, level, doc_path) plus depth. For a read-only path tool, this is comprehensive and 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 covers 100% of parameters with descriptions. The description does not add extra information about parameters beyond the schema, so baseline score of 3 applies.

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

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

The description clearly states it returns 'breadcrumb chain' for a section_id, using specific verb 'return' and resource 'breadcrumb chain'. It distinguishes from sibling tools like get_toc, get_toc_tree, and get_section by focusing on path traversal.

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 version requirement 'v1.40+' and mentions cycle-protection, but does not explicitly state when to use this tool vs alternatives like get_section_context or describe_section. Usage context is implied but not directly addressed.

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 behavioral context: unknown IDs produce per-ID errors rather than failing the entire call, and only explicitly requested section content is returned. This goes beyond the annotation without contradicting it.

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

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

Two concise sentences with the primary purpose front-loaded and no filler. The second sentence adds critical error-handling nuance without bloat.

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 effectively covers the core retrieval behavior and error semantics. While there is no output schema, the tool's behavior is simple enough that the description is nearly complete; the main omission is any mention of the return shape, but that is not critical for this kind of batch content retrieval.

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 five parameters including defaults and behaviors for verify, compress_code, and strip_boilerplate. The description adds no additional parameter-level semantics, 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?

The description clearly states the tool performs 'batch content retrieval for multiple sections in one call', distinguishing it from single-section tools like get_section and summary-focused tools like get_section_summaries. The scope ('Content only for the ids you pass') is explicitly defined.

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 conveys clear context for use: batch retrieval across multiple section IDs in one call. It does not explicitly name alternatives or state when not to use it, but the 'in one call' phrasing implies it as the batch counterpart to single-section retrieval.

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 detailed behavioral context beyond readOnlyHint: batch processing, single index load, inline error reporting, and no abort on per-ID errors.

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

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

Two sentences efficiently convey identity, relationship, and key behavior 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?

Covers batch behavior, error handling, and correlation pattern despite no output schema; could benefit from performance or limit notes.

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 provides complete parameter descriptions (100% coverage), so description adds minimal extra meaning; only mentions order preservation and correlation IDs already in 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 it is a batch version of get_section_summary for resolving metadata for many IDs, distinguishing it from single-use 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?

Explicitly describes use for batch calls and inline error handling, implying use when multiple IDs are needed, but lacks explicit alternatives or when-not-to-use.

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

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

Annotations indicate readOnlyHint=true, which is consistent with the description's read-only nature. The description adds version requirement (v1.38+) and lists all returned fields, providing behavioral context 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, front-loaded with version and purpose, no wasted words. 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?

Despite no output schema, the description comprehensively lists all returned fields, compensating fully. For a metadata inspection tool with two well-documented parameters, this 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 baseline is 3. The description adds minor context about section_id origin (from get_toc, search_sections, etc.), but does not significantly enhance parameter 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 it returns full indexed metadata (title, summary, role, tags, etc.) for one section without fetching content. The verb 'return' and resource 'metadata' are specific, and it distinguishes from get_section which fetches 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?

Explicitly states 'Use to inspect role/tags before deciding whether to read the content via get_section.' This provides clear when-to-use and 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?

Beyond the readOnlyHint annotation, it discloses the data sources (in-memory latency ring + persistent savings counter) and the behavioral consequence of server restart on the ring. This helps interpret results and confirms the read-only nature.

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 convey the purpose, output, data source, caveat, and sibling alternative with no filler. Every phrase 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?

For a zero-parameter, read-only tool with no output schema, the description fully covers what it returns, where data comes from, and when to use an alternative. It is complete for an agent to decide invocation 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 tool has zero parameters, so the baseline of 4 applies. The description adds no parameter details, but none are needed given the empty schema.

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

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

Clearly states the tool returns {latency_per_tool, total_tokens_saved}, specifying both the resource (session stats) and the exact output. Distinguishes from siblings by naming analyze_perf for windowed analysis.

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 provides an alternative: 'For windowed analysis use analyze_perf.' The 'lightweight' descriptor implies quick monitoring, and the in-memory caveat tells users when values reset.

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?

Beyond the readOnlyHint annotation, it discloses that the result is 'flat' and 'sorted by document order', excludes content, and has no doc_path parameter. These are behavioral traits not covered by annotations, enhancing transparency.

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

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

Three concise sentences front-loaded with the core function, followed by necessary caveats and alternatives. Every sentence earns its place 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?

For a simple read-only list tool with two parameters, the description is complete: it covers scope, output nature, exclusions, and alternatives. No critical gaps for an agent to understand usage and 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 'Scope with path_glob' and contrasting with doc_path, but most parameter details are already in the schema. Minimal value added beyond structured data.

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 'Get a flat table of contents for all sections in a repo, sorted by document order' with specific verb and resource. It explicitly distinguishes itself from get_document_outline and get_section, making its 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?

Provides explicit guidance: content is excluded, use get_section for content; for a single document use get_document_outline; scope with path_glob. This clearly specifies when to use this tool versus alternatives.

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

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

Annotations already set readOnlyHint=true, so the description adds value by disclosing that content is excluded and that it returns a nested structure. This goes 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?

Two concise sentences that are front-loaded with the core action and quickly provide key detail. No wasted words.

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

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

Given the tool's simplicity, read-only nature, and complete schema coverage, the description adequately covers what the tool does and its key differentiators. A brief mention of the output structure or pagination would have made it more 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. However, it adds no additional meaning beyond the schema descriptions. 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 uses a specific verb ('Get') and resource ('nested table of contents tree per document'), and explicitly states it shows parent/child heading relationships and excludes content, distinguishing it from siblings like get_toc or get_document_outline.

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 explicit guidance on when to use this tool versus alternatives such as get_toc or get_document_outline. The description implies its purpose but does not provide when-to-use or when-not-to-use context.

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

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

With readOnlyHint=true already signaling safety, the description adds valuable behavioral details: the exact detection mechanisms (frontmatter keys, inline links, numeric prefixes), the return shape, and the fallback behavior for unsupported wiring. This goes beyond what the annotation provides and covers edge-case expectations.

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 dense sentences with no filler or repetition. It front-loads the core purpose, then adds mechanism, output, and a caveat—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 only two scalar string params and no output schema, the description is quite complete: it explains purpose, detection strategy, output shape, and failure behavior. Minor omissions like what a valid repo or section_id looks like are not critical for this narrow 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 description coverage is 0%, so the description must compensate, but it only clarifies that section_id is the starting point. The 'repo' parameter is never explained, and section_id format/valid values are left unspecified. The description provides some meaning for one parameter but fails to fully compensate for the absent schema descriptions.

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 ('Reconstruct'), names the resource ('ordered tutorial chain'), and specifies the starting input ('section_id'). It also lists the detection conventions and the output (chain[] plus strategy), which clearly distinguishes it from sibling navigation tools like section_neighbors or get_section_path.

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

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

The description gives clear context: it detects three specific conventions and explicitly warns that tutorials wired any other way return a short chain, giving the agent a practical when-to-trust boundary. It does not name alternative sibling tools directly, but the limitation statement effectively communicates when not to rely on this tool.

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

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

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?

With only readOnlyHint=false in annotations, the description carries the full burden of behavioral disclosure and does so thoroughly. It discloses existing-index reconciliation, conflict/duplicate behavior, bounded ambiguity for legacy indexes, embedding auto-enablement, and precise `truncated`/`skip_counts` semantics. It also clarifies that office documents are converted locally, which is important non-obvious 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?

Every sentence carries non-redundant information, and the core purpose is front-loaded in the first clause. However, the description is a dense wall of semicolon-heavy prose with long parentheticals, making it harder to scan than ideal. For a 14-parameter tool it is appropriately sized, but not exemplary in structure.

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 mutating tool with 14 parameters and no output schema, the description covers many high-risk edge cases: duplicate indices, legacy reconciliation, truncation, oversize files, and embedding provider activation. The main gap is that the returned handle/response payload is not explicitly described beyond the coverage-related fields. It is still sufficiently complete for correct invocation.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds real semantic value beyond the schema by clarifying that `truncated` answers only the max_files cap and that oversize files appear under skip_counts.oversize. It also explains behavior of the handle/name layer, which affects how `name` and `paths` are interpreted. This elevates it above the baseline.

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

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

The first sentence states a specific verb and resource: 'Index a local folder containing documentation files,' and enumerates the supported formats. The heading-hierarchy parsing and embedding details make the operation unmistakable. The 'local folder' scope clearly distinguishes it from the many retrieval-oriented siblings and the repo-centric index sibling.

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

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

The description gives clear context: this tool is for indexing local documentation folders, with format caveats and optional configuration conditions. It does not explicitly name an alternative such as doc_index_repo or state when-not-to-use this tool, so it stops short of a 5. The context is clear enough that an agent can select it appropriately.

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.

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

The readOnlyHint annotation already signals non-mutating behavior, and the description adds details like sorting by doc_path and exclusion of section titles/content, providing additional behavioral transparency 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?

The description is a single, well-structured sentence with front-loaded version and purpose, including a contrast with a sibling tool, without any redundancy or unnecessary 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?

The description covers output fields, sorting, exclusions, and a comparison to get_toc_tree, making it complete for a simple tool; minor omissions like error handling are not critical for this 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 already describes the 'repo' parameter as a repository identifier; the description does not add further semantic detail, but the single parameter is adequately covered for the tool's purpose.

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 provides a flat per-doc inventory with specific fields (doc_path, section_count, format, byte_size), and explicitly contrasts with get_toc_tree, making 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?

Explicitly mentions when to prefer it over get_toc_tree (lighter) and what it does not return (no section titles/content), giving clear guidance on appropriate use cases.

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

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

Annotations already declare readOnlyHint=true, so the description adds value by specifying exact matching behavior. However, no additional behavioral traits (e.g., pagination, limits, or effects) are disclosed 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?

Two sentences that efficiently convey purpose and relationship to sibling. 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?

Adequate for a simple query tool with readOnlyHint. However, it lacks explanation of the 'repo' parameter and the format of the returned operations, leaving some gaps in completeness.

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

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

With schema description coverage at 0%, the description must compensate. It explains the 'tag' parameter (exact match) but does not explain the 'repo' parameter, which is required. The description only hints at a tag filter, leaving the repo parameter's role 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?

Clearly states verb 'Return', resource 'every operation', and condition 'tags list contains the given tag (exact)'. Also explicitly notes it is a convenience wrapper around find_endpoint, distinguishing it from that 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?

Describes itself as a convenience wrapper around find_endpoint with only a tag filter, implying it should be used when filtering solely by tag. However, it does not elaborate on when not to use it or mention other alternatives beyond find_endpoint.

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 include readOnlyHint=true, and the description does not contradict this. The description adds valuable behavioral context beyond the annotation: it clarifies that the tool only lists definitions and does not verify index status, and mentions the version requirement. This is useful transparency without being verbose.

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, directly states the core function, and immediately adds the key caveat about not checking index status. There is no fluff, and the information is front-loaded. Every phrase 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?

For a simple tool with no parameters and no output schema, the description covers the essential aspects: what it lists, the version prerequisite, and the limitation regarding member repo indexing. It provides enough context for an agent to decide when to use it and what to expect. No further details are necessary.

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

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

The tool has zero parameters, and the schema is empty. Per the baseline rule, 0 params yields a score of 4. The description doesn't need to explain parameters, and it doesn't try to invent any. It correctly focuses on what the tool returns and its constraints.

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 lists defined repo groups, specifying it's a version-specific (v1.26+) operation. It distinguishes the purpose by explaining that each group is a named alias for indexed repos used by search_sections, which differentiates it from other list tools (e.g., list_repos) and the sibling define_repo_group.

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 by explaining the tool's role in the context of search_sections and repo_group, and explicitly notes a limitation ('does not check that every member repo is still indexed'), which warns when not to rely solely on this tool. However, it doesn't name alternative tools or provide explicit when/when-not scenarios beyond the caveat.

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