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

Annotations already declare readOnlyHint=true, and the description adds real context beyond that: the score blends four named dimensions, blast radius is derived from impact files, and the return includes sub-scores, drivers, and recommendations. It stops short of disclosing analysis cost or which repository data is read, but for a read-only scoring tool this is meaningfully informative.

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?

One dense paragraph, front-loaded with what the tool does and why the score exists. Each clause earns its place, though the four-dimension parenthetical is jargon-heavy and could be easier to scan as a list.

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 scoring tool with full schema coverage and no output schema, the description covers the score's composition and return shape well enough to call it correctly. Minor gaps remain around analysis cost and repository scope, but nothing essential is missing.

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

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

Schema coverage is 100%, so the schema itself documents all four parameters, including top, path, query, and includeMarkdown. The description only indirectly illuminates 'top' through its mention of blast radius and impact files; otherwise it adds no parameter detail beyond the schema. 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 and resource ('Score Agent Experience') and defines the composite metric precisely, including its four sub-dimensions. It does not differentiate this from plausible siblings such as convergence_score, review_gate, or change_impact, so an agent must infer the boundary.

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

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

Usage is implied by the framing: score a plain-English change request to learn how cheap and safe it is for an agent. There is no explicit when-to-use or when-not guidance, and no sibling tool is named as an alternative, so the agent is left to infer routing.

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

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

Annotations declare readOnlyHint=true, and the description reinforces this with 'nothing is written' twice and 'returns the amended record under intent without ranking anything'. It also discloses the extra behavior of diffBase (exact changed-file evidence) and the companions behavior driven by .solumberc.json, which annotations alone would not convey.

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

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

Three sentences, front-loaded with the core ranking purpose before the optional diffBase and companions clauses. It is dense but every clause carries information; the companions sentence is the only one that could arguably be trimmed.

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

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

For a 9-parameter tool with a nested amend object and no output schema, the description still explains what results come back (ranked files, risk flags, tests, plan, intent record, companions) and the two-mode behavior (ranking vs. amend/declare). An agent has enough to call it correctly and interpret 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 coverage is 100%, so the baseline would be 3, but the description adds meaning beyond the schema: what diffBase actually does ('surfaces exact changed-file evidence'), what declare freezes, and what companions carries. Minor params like top and path are left to the schema, which is acceptable given full 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 a specific verb and resource: 'rank the files most likely to own the change', and enumerates the concrete outputs (risk flags, suggested tests, implementation plan). This is clearly distinguishable from siblings like review_gate or repo_search, which are about gating and locating rather than impact ranking.

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

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

It gives explicit workflow guidance: 'Call it before editing, then pass that record to review_gate as intent', and explains that diffBase validates predictions against a git ref. It does not state outright when NOT to use the tool or contrast it with review_context, but the context it does provide is strong and actionable.

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 readOnlyHint/openWorldHint, it discloses that default behavior is deterministic and that online:true reaches an external read model, gracefully degrading ("without either the pack is unchanged") when no key is set. It also explains that includeEvidence defaults off to keep the packet compact. Costs such as runtime or file-count tradeoffs are not mentioned, keeping it 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?

Two tightly packed sentences: the first defines the artifact, the second defines the only behavioral branch (online). No filler, no repetition of the schema, and the core output 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?

With no output schema and seven parameters, the description does the necessary work: it names the packet's sections, the deterministic default, and the online augmentation path. What remains thin is the shape of the returned packet and multi-repo behavior, both of which live entirely in the schema descriptions.

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 outcome semantics the schema lacks: online results surface under modelRead and only confident answers are applied, and includeMarkdown switches the return shape to a markdown report. That goes beyond merely restating parameter names.

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 ("Generate a task-aware local context packet") and enumerates the packet's contents: primary files, related files, tests, validation commands. That is far more informative than the title, but it never names a sibling, so an agent must infer on its own that this differs from repo_search, repo_map, or review_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?

The description signals the main usage fork (deterministic by default vs. online:true consulting a read model) and the API-key prerequisite. It never says when this tool should be chosen over repo_search or review_context, or when a local packet is the wrong choice, so routing context is only implied.

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

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

Even though annotations only state readOnlyHint=false, the description adds substantial behavioral context: no model is used, scoring is deterministic, an inconclusive band exists, a recomputable receipt is emitted, and untracked/staged/head behavior is clarified. This gives an agent real insight 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 front-loaded with the core purpose and stays compact despite covering the scoring model, sub-scores, inconclusive cases, receipt, and subject selection. Each sentence adds useful information without repetition.

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

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

For a complex 9-parameter tool with no output schema, the description covers the essential invocation context and output meaning at a high level: score range, sub-scores, inconclusive band, and receipt. It still does not describe the full JSON return shape or all mode interactions, so it is strong but not 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%, so the parameters are already well documented. The description adds high-level meaning for base, head/staged subject selection, and intent-vs-diff scoring, but it does not explain most individual parameters such as top, includeMarkdown, includeUntracked, or path beyond what the schema already says.

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

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

The description gives a specific verb and resource: score convergence as a deterministic 0–100 distance between stated intent and git diff, with named sub-scores. It is clearly a scoring operation unlike the sibling tools, but it does not explicitly contrast itself with alternatives such as change_impact or review_gate.

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 operational context—base is required, working tree is scored by default, and head/staged select alternate subjects—but it does not state when to choose this tool over sibling tools or when not to use it. Usage is implied rather than explicitly routed.

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

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

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 description adds real behavioral context beyond readOnlyHint=false: indexing writes to the persistent local catalog, dryRun is genuinely read-only, and without it the call mutates state. It explicitly warns 'it is not a pure read', so the mutation profile is clear.

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, then the two mode flags, then the mutation warning. No filler; the read-only caveat is worth its space.

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 7-parameter mutation tool with no output schema, the description covers the action, the two critical flags, and the side effects. It doesn't say what the indexing produces in terms of reported results, 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 coverage is 100%, so the baseline is 3; the description nevertheless explains the effect of two key flags (discover and dryRun) in terms of behavior, not just type. The remaining parameters (path, paths, depth, limit, catalog) are left to the schema.

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

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

The description gives a specific verb+resource ('Index local repositories') plus concrete outputs (per-user external indexes, local catalog), which clearly separates it from inspection/mapping siblings like repo_map and repo_inspect. It never names a sibling directly, so it stops short of a 5.

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

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

It clearly states the conditions selecting each mode: discover:true to find roots first, dryRun:true to report without writing. What is missing is any guidance on when to prefer this over a sibling such as repo_inspect or repo_map.

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?

The readOnlyHint annotation already establishes this is a safe read, so the description only needs to add context. It contributes the output being a compact JSON code map and clarifies route matching semantics, but says nothing about cost on a large repo, truncation behavior, or how includeFiles changes the payload.

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

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

Two dense sentences with the core action front-loaded and the filter options following immediately. No filler, though the second sentence partially duplicates parameter text.

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

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

With six optional parameters, a 100% covered schema, and no output schema, the description supplies the one thing structured data cannot: what the tool returns ('compact JSON code map'). Filters, defaults, and the read-only nature are all 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 schema already documents all six parameters including the kind examples and the route substring/regex semantics. The description largely repeats that content ('route to match Nest controller routes by substring/regex') rather than adding meaning, so this lands at 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 description names a specific verb and resource ('Map a repository') plus the output shape ('compact JSON code map'), which is more than a restatement of the title. It does not explicitly distinguish itself from close siblings like repo_index or repo_inspect, so an agent must infer that this produces structure rather than raw search results.

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 second sentence gives conditional guidance for each filter ('Pass domain to find files for a feature, kind to find files of a type, route to match Nest controller routes'), which is useful in-tool routing. However, there is no statement of when to choose repo_map over repo_search, repo_index, or repo_inspect, and no 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?

readOnlyHint=true already tells the agent this is a safe read; the description adds useful scope behavior (default working directory, catalog fallback when outside a repository). It says nothing about index freshness, whether results reflect stale fingerprints, or how offline interacts with search, leaving behavior beyond annotations thin.

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 front-loaded sentences that cover scope, listing mode, and widening options with no filler. The final sentence ('Outside a repository it searches the catalog') repeats the catalog fallback already implied earlier, a minor redundancy.

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

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

For a read-only search with fully documented parameters, this covers how to target repositories and how to switch to listing mode. With no output schema, it could still say what a match or catalog entry looks like, which is the one remaining gap.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real precedence semantics the schema does not: path is the default target, paths replaces it, all: true adds every catalog repo, and query omission switches from search to listing. Those interactions are genuinely useful beyond the per-field 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 gives a specific verb (search) and resource (indexed local repositories) and enumerates the searchable facets: path, domain, kind, route, imports, exports, symbols. It also clarifies that omitting the query lists the catalog instead. It doesn't differentiate from look-alike siblings such as repo_map, repo_inspect, or repo_harness, so it falls short of 5.

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

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

It clearly states when to omit query (catalog listing), the default scope (the repo at path, working directory by default), and two ways to widen scope (paths, or all: true with repo_index to add repositories). It doesn't say when to prefer repo_map or repo_inspect over this tool, so alternatives are only partly covered.

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

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

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?

The description adds genuine behavioral context the annotation does not: mode-dependent check sets, the 'SKIPPED never changes the verdict' rule, and the implicit `gh` CLI dependency in PR mode. However, annotations declare readOnlyHint=false while the description never discloses any side effects or writes (e.g. whether a convergence receipt is emitted), which is a real gap for a tool flagged as non-read-only.

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 verb and verdict, then mode behavior, then alternatives — a logical order with no filler sentences. The long parenthetical enumerations of checks in each mode make it dense, but each item is substantive information an agent cannot get elsewhere.

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 an 11-parameter, no-required-parameter tool with no output schema, the description covers verdict values, mode selection, check enumeration, and skip semantics — enough to call it correctly. It falls short only on side effects given readOnlyHint=false, which matters for a non-read-only tool.

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

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

Schema coverage is 100% with all 11 parameters documented, so the schema already carries parameter meaning, making 3 the baseline. The description reinforces the pr-versus-local mode switch and the base-ref scoping, but adds no syntax or format detail beyond what the schema states (e.g. no guidance on valid intent or receipt shapes).

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 concrete verb and outcome ('Gate a change for merge and return a PASS / WARN / FAIL verdict') and then differentiates two modes by name. It explicitly names the siblings review_verdict and review_context and states how they differ, so an agent can distinguish this tool from all 13 siblings without opening a schema.

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

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

It gives explicit when-to-use rules for both modes ('Omit pr' vs 'Set pr') and names two alternatives with the exact condition that selects each ('full impact + review + gate composite', 'diff/comment context with no verdict'). Nothing about routing 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?

Annotations only declare readOnlyHint=true; the description goes further by disclosing the composition (three sub-tools run in one shot), the derived confidence score, and the conditional behavior where impactSummary.companions is populated only when .solumberc.json lists companions and a request is supplied. It does not spell out cost/latency of running three pipelines at once or what the gate outcome looks like, so not 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?

Front-loads the composition and return value, then conditions, then sibling routing — a sensible order. Slight redundancy between 'Run the full review pipeline in one shot' and 'Use review_verdict when you want the complete picture ... in a single call', which repeats the same point.

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

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

An 11-parameter, all-optional tool with no output schema needs coverage of the input space and the return shape; the description covers the unified verdict plus one notable return field, and the schema covers the rest. The procedural meaning of the receipt/intent/minConvergence trio is left to the schema, which is acceptable but leaves some ambiguity about ordering.

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

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

Schema coverage is 100%, so the schema already documents all 11 parameters including defaults and enum-ish values like policy and governance. The description adds meaning only for the `request` parameter, tying it to companion file ownership, which is a genuine but small increment. Baseline 3 is appropriate.

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

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

States a specific verb and resource — running the full review pipeline as a composition of change_impact, review_context and review_gate — and names the return artifact (unified verdict with derived confidence score). Explicitly contrasts itself with review_context and review_gate, so an agent can pick the right tool without reading schemas.

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

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

Gives a positive selection rule ('when you want the complete picture of a change in a single call') and names two alternatives with their narrower scopes ('diff metadata only (no verdict)', 'gate verdict alone'). No inference required.

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.