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

The description goes well beyond the readOnlyHint annotation by explicitly stating that it 'leaves the target repository unchanged' and disclosing a real side effect: it 'uses a per-user external cache.' It also adds determinism and composition guarantees, which are important behavioral traits not visible in the schema or annotations. There is no contradiction: the cache note qualifies the read-only guarantee.

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 earns its place: the first defines the metric in plain terms, the second explains composition and determinism, the third states the return payload, and the fourth discloses side effects and safety. The core purpose is front-loaded)Skip, and the language is dense without being padded.

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

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

Because there is no output schema, the description compensates by specifying the return shape at a useful level: 'sub-scores, drivers, and concrete recommendations for raising AX,' plus the markdown option. It could go slightly further on cache behavior or failure semantics, but for a deterministic read-only scoring tool with a fully documented input schema, this 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 description coverage is 100%, so the schema already documents all four parameters. The description does not add significant new meaning about parameter formats or edge cases; it only reinforces the spirit of the query parameter by describing the change request as 'how cheap and safe is it for an agent to make this change here?' This meets the baseline but does not exceed it.

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

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

The description opens with a specific verb and resource: 'Score Agent Experience (AX): a single 0–100 number.' It then defines what AX measures (cheapness/safety of a change) and lists its four components, making the tool's purpose unmistakable and clearly distinct from the raw engines it composes, such as change_impact.

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

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

The description gives clear context for when to use this tool: when an agent needs an aggregate AX score and concrete recommendations rather than raw engine output. It states that the tool is 'composed from the change_impact, token-estimate, and CODEOWNERS engines — no new analysis,' which implicitly positions it as the higher-level or synthetic choice among sibling tools, though it does not explicitly list exclusions.

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

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

Annotations already declare readOnlyHint=true, and the description adds useful behavioral context: it leaves the target repository unchanged, uses a per-user external cache, and can combine heuristic ranking with exact diff evidence. 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?

Two sentences with the main action and outputs front-loaded. Every sentence adds information: what the tool does, what it returns, when the optional diff base matters, and its cache/read-only behavior. No filler.

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

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

There is no output schema, but the description explains the return payload components: ranked files, risk flags, suggested tests, and an implementation plan. It also notes the optional exact-evidence mode, external cache, and non-mutation, which is enough for an agent to select and invoke it correctly.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds meaning by characterizing query as a plain-English change request and diffBase as providing exact changed-file evidence alongside the heuristic, going beyond the schema.

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

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

States a specific verb and resource: 'Given a plain-English change request, rank the files most likely to own the change' and enumerates the outputs (risk flags, suggested tests, implementation plan). This clearly distinguishes it from sibling repo inspection/search 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?

Clearly frames when to use the tool: when there is a plain-English change request, and when to use the optional diff base to surface exact changed-file evidence. It does not explicitly name alternatives or exclusions, but the usage context is unambiguous.

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

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

Annotations only declare readOnlyHint and openWorldHint; the description adds substantive behavior beyond that: a per-user external cache, determinism by default, a network/auth dependency (TYPESAFE_API_KEY) for online mode, and the concrete side effects of that mode (relabeling a confidently read intent, demoting files judged irrelevant, reported under modelRead). The 'leaves the target repository unchanged' line overlaps the readOnlyHint but usefully confirms write safety.

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 purpose before the optional online mode, with no filler. The third sentence is dense and somewhat run-on, but every clause carries information about behavior the agent needs.

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, cache-backed generation tool with no output schema, the description covers what is produced, the default behavior, the opt-in network path and its prerequisites, and a named output field (modelRead). An agent has enough to invoke it correctly without opening the schema, and return-value detail is minimal since the packet structure is described inline.

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

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

Schema description coverage is 100%, so the baseline is 3. The description's online explanation largely restates the schema's own description of that flag (intent reading, confidence gate, TYPESAFE_API_KEY, offline fallback), adding little beyond the schema, and it says nothing about path, paths, limit, includeEvidence, or includeMarkdown.

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

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

States a concrete verb and resource ('Generate a task-aware local context packet') and enumerates the packet's contents (primary files, related files, tests, validation commands), which distinguishes it from simpler retrieval siblings like repo_search or repo_map. It stops short of naming which sibling to prefer when, so it is clear but not fully 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?

Gives real usage conditions for the optional mode ('pass online:true to also ask a System One model... needs TYPESAFE_API_KEY') and notes the deterministic default, so the intended workflow is implied. However, it never states when to choose context_pack over alternatives such as review_context, repo_inspect, or change_impact, leaving sibling selection to inference.

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

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

Beyond the sparse readOnlyHint=false annotation, the description discloses determinism, the absence of model analysis, the recomputable timestamp-free receipt, the default working-tree subject, and the side effect that staged mode 'may create Git object or index-cache metadata' while source files remain unchanged. This is rich behavioral context that helps an agent anticipate side effects and reproducibility.

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

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

The description is dense but every sentence earns its place: definition, sub-scores, composition, scope rules, receipt, and mode selection. It is front-loaded with the core purpose and avoids filler or repetition of schema details.

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

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

Given the tool's complexity—8 parameters, no output schema, and a rich sibling set—the description covers the essential invocation context: what is measured, how scope is determined, how modes alter the subject, side effects, and the durable receipt. An agent has enough to select and call the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful cross-parameter semantics: it explains that head and staged select an exact subject instead of the working tree, that includeUntracked only applies in working-tree mode, and that staged can create metadata. This goes beyond the individual parameter descriptions in 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 opens with a specific verb and resource: 'Score convergence: a deterministic 0–100 measure of the distance between a stated task (intent) and the actual git diff (execution).' It names the three sub-scores and explicitly distinguishes itself from the sibling change_impact tool by stating it is 'composed from the change_impact diff comparison' rather than being a raw diff 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 gives clear context for invocation: it requires a base git ref, defaults to the working tree, and explains the head/staged modes. However, it never explicitly states when to choose this tool over siblings like change_impact, review_gate, or model_route, nor does it provide exclusions or alternative 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?

Discloses behavior well beyond the annotations: the model is only called when TYPESAFE_API_KEY is set and offline is not true, otherwise a labelled offline estimate is returned, and model.source indicates which path ran. It also explains the deterministic+System One blend and the advisory-only contract. This is rich context an agent could not infer from readOnlyHint/openWorldHint alone.

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

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

Front-loaded with the core purpose, then progressively adds the auth/offline condition, the advisory contract, and the host mapping. Dense but every sentence carries information; a touch long, but nothing is 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 6-parameter advisory tool with no output schema but a markdown-report option, the description covers the return signal (model.source), the fallback path, and the host mapping. An agent has enough to call it and interpret the result, though it never mentions the 'top' impact-file parameter.

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

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

Schema coverage is 100%, so the baseline is 3; the description still adds meaning by explaining what host does (maps the tier to that host's model id) and tying offline to the labelled-estimate fallback and model.source. It reinforces, though does not fully replace, the schema's parameter docs.

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

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

States a specific verb+resource: 'Recommend a model tier (cheap, mid or premium) for a coding request before any work starts.' It also separates itself from siblings by noting it is advisory and 'never feeds review_gate or review_verdict', so an agent can tell it apart from the review tools without opening any schema.

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

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

Gives clear context (use before any work starts, for routing a change request) and names the review_gate/review_verdict alternative it is not. It stops short of stating explicit when-not-to-use cases beyond the advisory disclaimer, but the routing intent is unambiguous.

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

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

The annotations declare readOnlyHint: true, so the description does not need to repeat that. It adds a behavioral detail: it can generate different types of commands (setup, validation, runtime, context) and can optionally return a markdown report (via includeMarkdown) or full JSON. This goes beyond what annotations provide, clarifying the output format options and the scope of generated content.

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 one sentence, concise and clear, with the verb first ('Generate') and the main part stated upfront. It efficiently conveys the purpose without unnecessary words. It could be slightly improved by mentioning the markdown option in the description for completeness, but it is already moderately concise and well-structured.

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

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

For a read-only tool with no required parameters and a 100% schema description coverage, the description covers the essential purpose and basic behavior. It does not mention return values, but since there's no output schema and the schema covers parameters, the description is sufficient for an agent to understand what the tool does. The lack of detail on how to use the output (e.g., how to interpret the generated commands) is a minor gap.

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

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

Schema description coverage is 100%, so the schema already documents both parameters adequately. The description does not add semantic detail beyond what the schema provides—e.g., it doesn't explain how 'path' might affect command generation or what 'includeMarkdown' changes in detail. Given the high coverage, a score of 3 is appropriate as a 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 states a specific verb ('Generate') and a set of resources ('setup, validation, runtime, and context commands'), which clearly identifies the tool's purpose. However, it does not explicitly differentiate it from sibling tools like 'context_pack' or 'workspace_report', which might also generate context-related outputs. The phrase 'for an agent or CI harness' adds useful context but does not distinguish between the tool and its 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 implies usage in the context of an agent or CI harness (when you need to generate commands), but it does not explicitly state when to use this tool versus alternatives like 'repo_inspect' or 'context_pack'. There is no mention of conditions or exclusions. The phrasing 'Generate ... commands' gives a hint that it's for command generation, but without explicit guidance, an agent might struggle to select the right tool among siblings.

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

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

The annotation readOnlyHint is false, and the description aligns with that by stating 'Without dryRun this mutates the persistent local catalog, so it is not a pure read.' It also discloses that dryRun is read-only. This goes beyond the annotation by specifying the exact mutation target (catalog) and the read-only mode. No contradictions detected.

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—three sentences total. It front-loads the primary purpose, then covers key options (discover, dryRun) and a critical caveat about mutation. Every sentence carries useful information with no filler. Excellent 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 tool with 7 parameters (none required), no output schema, and no nested objects, the description covers the essential operational modes: discovery and dryRun. It explains the mutation side effect and the replacement of an older tool. It does not describe the return value or the format of the generated indexes, but since there is no output schema and the description is already focused on invocation behavior, this is adequate. A 4 is appropriate.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds value by explaining the functional interplay of dryRun and discover, e.g., 'Pass discover:true to find repository roots under the given paths first' and 'Pass dryRun:true to discover and report without writing any indexes.' This is beyond the individual parameter descriptions, providing usage semantics that help the agent decide how to set them. Baseline is 3 due to high coverage, but the added context 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 states a clear purpose: 'Index local repositories: generate per-user external indexes and add them to the local catalog.' It identifies the primary action and resource. It does not explicitly differentiate from sibling tools like repo_inspect or repo_map, but the verb 'index' and the mention of generating indexes is sufficiently distinct. A 4 is warranted because while the purpose is clear, it lacks direct sibling differentiation.

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

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

The description gives explicit guidance on using the dryRun parameter: 'Pass dryRun:true to discover and report without writing any indexes or catalog (read-only)' and explains that without dryRun it mutates the persistent catalog. It also mentions that dryRun replaces the old repo_discover tool. However, it does not compare this tool to alternatives like repo_inspect or repo_map, so the guidance is mostly about parameter usage rather than when to choose this tool over others. This is a solid 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?

Annotations provide readOnlyHint:true, and the description adds valuable behavioral details: it returns up to 200 representative file paths and explains that includeScripts:true yields full script bodies instead of names. These specifics go beyond the annotation and help the agent predict output shape and parameter effects.

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 zero redundancy. It front-loads the core purpose, then adds a key output limit and the conditional includeScripts behavior. Every sentence earns its place.

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

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

For a simple tool with two optional parameters and no output schema, the description provides the essential purpose, key output characteristics (up to 200 paths), and a notable behavioral switch. It lacks details on return structure (e.g., exact schema of metadata), but that is minor given the tool's 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 coverage is 100% with clear descriptions for both parameters. The description adds little beyond the schema—it mentions includeScripts behavior, but that is already captured in the schema. No additional parameter context is provided, so baseline 3 is appropriate.

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

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

The description uses a specific verb 'Inspect' with a clear resource 'repository' and enumerates concrete aspects: shape, languages, package managers, script names, entrypoints, and git metadata. This distinguishes it from sibling tools like repo_map (mapping) and repo_search (searching) by specifying the inspection scope.

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

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

The description implies usage by naming the tool's function, but it does not explicitly state when to use it over alternatives like repo_map or repo_index. There is no mention of exclusions or alternative routing, leaving the agent to infer from the name and sibling 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?

Beyond the readOnlyHint annotation, the description explicitly states 'Uses a per-user external cache and leaves the target repository unchanged,' which discloses side effects and safety. It also reveals that the output is a compact JSON code map and that this tool replaces four older tools, adding useful behavioral context 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 composed of four concise sentences, each carrying distinct information: core function, filter usage, legacy replacement, and caching/non-destructive behavior. It is front-loaded with the primary purpose and contains 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?

The description covers purpose, filter semantics, caching, and non-destructive behavior, and the schema fully documents all six optional parameters. However, it does not describe the structure or contents of the resulting 'code map' beyond calling it compact JSON, which is a notable gap given there is no output schema. An agent might not know what fields or sections to expect in the response.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds semantic meaning for the main filters: domain for feature files, kind for file types, and route for Nest controller routes. This clarifies intent beyond the schema's terse examples, especially by linking 'kind' to a specific list of file types.

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

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

The description states a specific action and resource: 'Map a repository into a compact JSON code map' with optional narrowing by domain, file kind, or route. It also names the legacy tools it replaces, clarifying that this is the consolidated successor for those search/filter operations. This makes the tool's purpose unambiguous and distinct from the sibling repo_* tools.

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

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

The description gives clear guidance on when to use each filter ('Pass domain to find files for a feature, kind to find files of a type...'), which is useful for parameter selection. However, it does not explicitly compare against current siblings like repo_search, repo_inspect, or repo_index; it only mentions replaced legacy tools. Thus, when-to-use versus current alternatives is implied rather than explicit.

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

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

Annotations already declare readOnlyHint=true, so the description doesn't need to repeat safety. It adds meaningful behavioral context: the dependency on a populated local catalog and the suggestion to run repo_index if empty. It also discloses that omitting query changes behavior to listing. 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 redundancy. The primary action is front-loaded, the secondary mode is explained, and the prerequisite is stated. Every sentence earns its place.

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

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

For a tool with 4 parameters, 0 required, and no output schema, the description covers the essential use cases: search, list, and the dependency on indexing. It also hints at return behavior ('no matches' vs. catalog listing). Given the annotations provide safety, nothing critical is missing for an agent to call it correctly.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters. The description adds little new parameter-specific meaning—it restates the query omission behavior already in the schema and adds the catalog dependency at the tool level, not per-parameter. Baseline 3 is appropriate.

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

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

The description states a specific verb ('Search') and resource ('indexed local repositories'), and enumerates the search dimensions (path, domain, kind, route, imports, exports, symbols). It also clarifies the dual mode (search vs. catalog listing) and references the legacy repo_catalog tool, making it easy to distinguish from 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 explains when to use the tool ('Omit query to list the catalog'), and when not to ('if the catalog is empty this returns no matches'), and directs the agent to call repo_index first. This is clear guidance with an explicit 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?

Annotation readOnlyHint=false already signals possible mutationais, and the description does not contradict that. However, the description does not disclose that setting comment=true creates or updates a GitHub comment; that critical side effect is only visible in the schema's parameter description. The description adds scope context but misses the write path.

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

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

Three tightly packed sentences with zero filler. The core purpose and scope come first, then explicit routing to alternatives. Every sentence earns its place.

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

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

The tool has seven parameters and no output schema, but the high-coverage schema plus this description cover the main invocation needs. It could add a note about GitHub auth/network requirements for the gh enrichment, but nothing essential is missing for basic tool selection and use.

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

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

Schema description coverage is 100%, so the parameters are already fully documented. The description adds the high-level concept of 'raw diff/comment context' but does not enrich individual parameter meanings beyond the schema, which matches the baseline for 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?

The description states 'Produce PR review context from local git diff metadata, optionally enriched with GitHub PR comments,' which names a specific verb, resource, and optional data source. It explicitly differentiates from siblings by saying this is raw diff/comment context, not a verdict, and names review_verdict and review_gate as the alternatives.

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

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

It gives direct when-to-use guidance: 'Use review_context when you want the raw diff/comment context for a change, not a verdict.' It also names the exact sibling tools for alternative scenarios, leaving little room for an agent to select the wrong 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 only declare readOnlyHint=false, so the description must carry behavioral weight. It usefully describes what each mode inspects and notes the tool merges two prior tools, but it does not disclose mutation side effects, permission/auth needs, or what the verdict contains. The side-effect hint about Git object/index-cache metadata lives only in the schema, not the description.

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

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

Front-loaded with purpose, then modes, then alternatives in three well-ordered sentences. The long parenthetical enumerations of checks are dense but informative; minor legacy-tool reference is the only slightly expendable 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 ten-parameter, no-output-schema, mutation-flagged tool, the description covers mode selection and alternatives thoroughly. It leaves return-value detail and mutation/permission behavior to the schema, which is a modest but real gap given the absent 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?

Schema description coverage is 100%, so the schema already documents all ten parameters in detail. The description reinforces the pr on/off branching but adds no syntax, format, or constraint detail beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb (gate), resource (a change for merge), and the concrete output (PASS/WARN/FAIL verdict). It explicitly separates the two operating modes (omit pr = local gate; set pr = GitHub PR gate) and names the legacy tools it consolidates, so an agent can distinguish it from siblings without opening the schema.

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

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

Gives explicit routing rules: omit pr for the local gate, set pr for the GitHub PR gate, and names two alternatives with the conditions that select them (review_verdict for the full composite, review_context for diff/comment context with no verdict). Nothing about when-to-use is left to inference.

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

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

readOnlyHint=true already covers the safety profile, and the description adds genuinely new behavior: this call composes three other tools and synthesizes a confidence score, which explains latency and result shape. It doesn't discuss permissions, rate limits, or how partial failures in the composed stages are surfaced, so it stops short of a 5.

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

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

Three tightly written sentences: capability first, then routing guidance. Every clause earns its place, with no restatement of the name or padding.

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 states what comes back (a unified verdict plus a derived confidence score), which is the essential return-value information for a read-only aggregator. It does not sketch the verdict's internal structure or how the composed stages' findings are merged, leaving a small gap.

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

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

Schema coverage is 100% and every parameter carries a rich inline description, including defaults and PR-vs-local gating behavior, so the schema does the heavy lifting. The description adds no parameter-level meaning beyond what is already documented, making the baseline 3 correct.

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

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

States a specific verb and composite resource: it runs the full review pipeline (change_impact plus review_context plus review_gate) and returns a unified verdict with a derived confidence score. It explicitly distinguishes itself from the sibling tools it composes, so an agent can select it without opening schemas.

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

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

Gives an explicit when-to-use condition ('when you want the complete picture of a change in a single call') and names two alternatives with the conditions that select them: review_context for diff metadata only, review_gate for the gate verdict alone. Nothing is left to inference.

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

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

The annotations already declare readOnlyHint=true, and the description adds no behavioral context beyond saying it 'generates' a report. It does not describe output format, aggregation behavior, scope limitations, or any side effects, so it relies entirely on the annotation for safety transparency.

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

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

The description is a single, well-structured sentence with no filler. The core action, scope, and subject are front-loaded, making it easy to parse quickly.

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

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

The tool is simple and read-only, and the schema covers parameters well, but the description does not clarify what a 'product-level report' contains or how the repositories relate. Since there is no output schema, a little more detail about the report's scope or contents would make it fully complete.

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

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

Schema description coverage is 100%, and both parameters (paths, includeMarkdown) are adequately described in the schema. The description itself adds no parameter-level meaning, 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 uses a specific verb ('Generate') and resource ('product-level report') and adds the scoping phrase 'across multiple related repositories,' which distinguishes it from single-repo sibling tools like repo_inspect or repo_map. However, it does not explicitly name a sibling, so differentiation is slightly implied rather than stated.

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

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

The phrase 'product-level report across multiple related repositories' clearly implies a multi-repo aggregation context, but the description never states when to prefer this tool over alternatives or when not to use it. With 12 sibling tools, explicit selection guidance would meaningfully improve the definition.

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