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

Annotations already declare readOnly/idempotent/non-destructive, so safety is covered. The description adds real behavioral detail beyond that: merge commits are excluded from the count, results are ranked by shared-commit count, and commits touching many files are skipped (the maxFilesPerCommit behavior). It does not mention cost/performance or result shape, but the output schema covers the latter.

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 operation and scope, then the value proposition, then the key optional usage pattern. No filler and no repetition of schema 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?

An output schema exists, so return values need no explanation, and all 8 parameters carry full schema descriptions. The description covers the non-obvious analytic semantics (merge exclusion, bulk-commit skipping, ranking) that an agent would otherwise have to guess from the schema alone.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds interpretive value by explaining what the 'file' filter actually does ('see what usually changes together with one file') and by tying 'often changed' to the minShared threshold and the merge-commit/bulk-commit exclusions. This helps disambiguate 'file' from 'path', which the schema alone leaves subtle.

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

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

States a specific verb and resource ('Find pairs of files that are often changed in the same commits'), with scope (last N days, merge commits excluded) and ordering (most shared commits first). This is clearly distinguishable from siblings like file_hotspots or file_history, which concern individual file churn rather than co-change pairs.

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 usage context: it 'reveals hidden dependencies that imports do not show, e.g. code and the config or test it always drags along,' and instructs 'Pass "file" to see what usually changes together with one file.' That tells an agent when this tool is the right one, but no explicit when-not condition or named alternative among the 12 siblings is offered.

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 the full safety profile (readOnly, idempotent, non-destructive, closed-world), so the description carries a lighter burden. It adds genuinely useful behavior beyond annotations only in the result-ordering clause ("oldest first") and the interpretation of last-author activity; the rest restates return content that the output schema already covers. No permissions, cost, or failure-mode context is offered.

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 core behavior and the oldest-first ordering are front-loaded in the first sentence, and the use-case framing comes last. It is dense but every clause conveys real information; the enumeration of return aggregates is somewhat lengthy given an output schema exists, keeping it from a 5.

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 a full output schema, complete parameter documentation, and annotations covering the safety profile, the description is sufficient for an agent to call the tool correctly. The main remaining gap is routing guidance against the many sibling analysis tools, which the description never addresses.

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 all six parameters (path, repo, limit, exclude, minAgeDays, inactiveDays) are already documented in the schema. The description adds no parameter-level meaning beyond what is in the schema, 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 states a specific resource and computed result: file age on HEAD, oldest first, with last author and author activity status, plus histogram/median/per-directory aggregates. An agent understands exactly what the tool produces. It does not, however, explicitly differentiate itself from adjacent siblings like file_hotspots or knowledge_map, which is the only thing separating this from a 5.

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

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

It gives clear situational context via two quoted questions ("which parts of the code nobody touches any more?", "where are we losing knowledge?"), which tells an agent when this tool is the right pick. It stops short of naming alternatives or exclusions (e.g. when to prefer file_hotspots or knowledge_map instead), so it does not reach 5.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so safety is covered; the description adds genuinely useful behavior: search is limited to HEAD (not all refs), matching is literal and case-insensitive, and results come back newest first. It does not describe result volume/paging, though limit is documented in the schema.

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

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

Two sentences, zero padding, front-loaded with the core capability and semantics before the use-case examples. Every clause carries information 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 six-parameter search tool with an output schema and full annotation coverage, the description supplies scope, match semantics, ordering and use cases. Only minor gaps remain (e.g. how filters combine, ordering guarantees with filters), which the schema largely handles.

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

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

Schema description coverage is 100%, so all six parameters are already documented in-schema (days, path, repo, limit, query, author). The description restates the optional narrowing filters ("time window, author and/or path") without adding format or interaction detail, so the baseline 3 applies.

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

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

States a specific verb and resource ("Search commit messages") plus the precise search surface ("subject and body on HEAD") and match semantics ("literal, case-insensitive"). This level of scoping clearly separates it from siblings like file_history, recent_activity and compare_refs.

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

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

Gives concrete usage context ("finding when and why something changed, e.g. a ticket id, a feature name or 'revert'" with example queries), which makes the intended scenarios obvious. It stops short of naming alternatives or stating when NOT to use it, so it does not reach the explicit routing level of a 5.

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

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint=false, so the safety profile is covered. The description adds behavior beyond that: the result is a directional divergence computation (head ahead of / behind base) with the actual commit list in newest-first order. It stops short of noting the effect of the limit default or how large divergences are truncated.

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, zero filler: the first defines the operation and its output shape front-loaded, the second supplies motivating examples. Nothing is repeated from the schema or annotations.

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

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

With an output schema present the description need not enumerate return fields, yet it still summarizes the key result (ahead/behind counts and commit identities). Safety is covered by annotations and the remaining four parameters are fully documented in the schema, so nothing an agent needs to invoke this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description still adds real meaning by disambiguating the direction of the comparison — head is measured ahead of and behind base — which the schema's terse "Ref to compare against" / "Ref to compare" phrasings do not make explicit.

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 (compare) and resource (two refs: branches, tags, commits) and specifies exactly what is produced: ahead/behind counts plus the specific commits, newest first. This is functionally distinct from every sibling (list_tags, stale_branches, commit_search), so an agent can route to it without opening the schema.

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

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

Gives concrete triggering scenarios ("how far behind main is my branch?", "what is on this branch that is not released yet?"), which tells the agent when this tool is the right choice. It does not, however, name alternatives or state when-not to use it versus siblings like stale_branches or list_tags.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so safety is covered. The description does add real context beyond that: counts are computed on HEAD only, not all refs, and output is ordered by activity. It omits that merge commits are excluded by default, a behavior that materially changes the counts.

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

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

Two tight sentences, zero filler, with the core scope constraint (HEAD, last N days) and ordering front-loaded before the optional path restriction.

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

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

With an output schema present, return values need no explanation, and the annotations cover the safety profile, so the description's scope details are largely sufficient. The one gap is silent merge-commit handling, which a caller counting commits would want flagged.

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 days, path, repo, limit and includeMerges are all documented in the schema. The description only echoes the days window and path restriction, adding no syntax or semantics beyond what the schema already carries. 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?

Specific verb (count) plus resource (commits per author), with scope (HEAD, last N days) and ordering (most active first) stated up front. An agent can distinguish this aggregation tool from commit_search or recent_activity, though the description never names or contrasts a sibling explicitly.

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

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

There is no when-to-use guidance and no mention of alternatives among the many commit-history siblings (recent_activity, commit_search, file_hotspots). The per-author framing implies its use case but leaves the agent to infer when to pick it over neighbors.

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

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

Annotations already declare readOnly/idempotent/non-destructive/openWorld=false, so the safety profile is covered. The description adds real behavioral value beyond that: newest-first ordering, rename-following semantics, and per-commit payload (historical path, lines added/removed).

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 written sentences: the core behavior and ordering are front-loaded, and the second sentence adds usage framing without redundancy. Nothing is wasted.

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

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

An output schema exists, so return values need not be fully explained, yet the description still previews the per-commit fields. With annotations covering safety and the schema covering parameters, nothing an agent needs to invoke this correctly is missing.

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

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

Schema description coverage is 100%, so path, repo, and limit are already documented in the schema. The description adds no parameter syntax or format detail beyond what the schema provides; 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?

Specific verb+resource+scope: 'List the commits on HEAD that changed a single file, newest first, following the file across renames.' An agent can distinguish it from commit_search or recent_activity by the single-file and rename-following scope, though no sibling is named explicitly.

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

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

Provides clear motivating contexts ('how did this file evolve?' and 'who reworked it, and when?') that map to real agent intents. It stops short of naming alternatives or stating when not to use it (e.g., vs commit_search for content-based lookup).

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/idempotentHint/non-destructive, so the safety bar is low; the description adds real behavioral context beyond them by disclosing that merge commits are excluded and how the 'fix' classification is derived. It does not mention cost, ordering ties or result shape, but the output schema covers returns.

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

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

Three sentences, each earning its place: the metric, an example invocation, and the analytical use case. The core ranking rule is front-loaded with the qualifying details appended.

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 a rich schema, full annotations and an output schema, the description only needs to convey what the tool computes, which it does clearly. Minor omissions — default 90-day window relevance and that filtering is scoped by repo/path — are adequately covered by the schema itself.

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, and the description adds genuine meaning on top: it demonstrates the purpose of the `types` parameter with a concrete example (["fix"]) and explains what that filter is for. The remaining parameters (days, path, repo, limit, exclude) get no additional description-side semantics.

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

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

The description gives a precise verb+resource+metric: 'Rank files by how many commits changed them in the last N days (merge commits excluded), with how many of those commits were fixes.' That is far more specific than the bare title 'File hotspots'. It does not explicitly contrast itself with likely-confusable siblings such as change_coupling, file_history or code_age, so it falls 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 states concrete use contexts ('spotting churn, risky areas and refactoring candidates') and gives a motivating configuration ('Pass types: ["fix"] ... find the files that keep breaking'). There is no explicit when-not-to-use or named alternative tool, which keeps it below 5.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), but the description adds real methodology: merge commits excluded, recency weighting, bus factor, and files depending on one person. It doesn't disclose cost/performance characteristics of a potentially long commit scan, which is the only notable gap.

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

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

Two tightly packed sentences with zero filler: the first defines the computation and its exclusions/weighting, the second names the outputs and use cases. Front-loaded with the core answer rather than preamble.

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

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

With an output schema present, return values need no explanation, and all seven parameters are schema-documented. What's missing is only marginal: no note on result limits/pagination behavior or the default-repo fallback, both of which an agent relies on the schema for.

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

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

Schema description coverage is 100%, so every parameter including days, halfLifeDays, and maxFilesPerCommit is already documented in the schema. The description restates the time-window and weighting concepts but adds no syntax or format detail beyond it, 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?

Specific verb+resource with scope spelled out: per-author share of knowledge for a file/directory, plus bus factor and single-person dependency count. It is clearly distinguishable from siblings like contributor_summary and file_hotspots, which the description implicitly disambiguates through its per-path focus.

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

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

It names two concrete decision contexts ('who should review this?' and 'who knows the auth module best?'), which tells the agent when this tool is the right call. It stops short of stating when-not to use it or naming an alternative sibling explicitly.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds genuinely non-derivable behavior: results are sorted newest first, a second derived value (latest tag reachable from HEAD) is returned, and 'unreleased work' is quantified as a commit count.

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 purpose and scoping detail front-loaded before the routing hint at the end. No filler, though the parenthetical '(releases)' and stacked output clauses make it slightly 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?

An output schema exists, so return-value documentation is not required, yet the description still conveys the shape of the result. With 100% schema coverage and a read-only annotation profile, essentially everything an agent needs to select and call this tool is present; only explicit negative routing is absent.

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

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

Schema description coverage is 100%, so both parameters ('repo' with its default-repo fallback and 'limit' with range/default) are fully documented structurally. The description adds no filter or pagination semantics beyond that, so the baseline 3 applies.

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

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

The description names a specific verb and resource ('List tags (releases)'), states the ordering ('newest first'), and enumerates the payload ('date and tagged commit', 'latest tag reachable from HEAD', 'commits since it'). It also disambiguates from nearby tools by naming release_notes_draft and compare_refs as separate concerns.

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

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

It gives an explicit usage condition ('Use it to find tag names for release_notes_draft or compare_refs'), routing the agent toward downstream tools rather than leaving intent to inference. It stops short of stating when *not* to use it (e.g. versus commit_search for commit-level queries), so it is clear context without 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, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds behavioral detail beyond them: results are ordered newest first, the author match is a case-sensitive substring, and scope is limited to HEAD. It stops short of noting pagination or truncation behavior against the limit.

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, zero filler, and the core scope (HEAD, last N days, newest first) is front-loaded before the optional filters. Every clause carries information an 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?

With an output schema present, return values need not be described, and all five parameters are documented in the schema at full coverage. The description supplies the operational context (window, ordering, filter semantics, scope) needed to invoke the tool correctly, so nothing material is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description genuinely adds meaning: it specifies the author filter is a case-sensitive substring and that the path filter is repository-relative, neither of which the schema states. It does not restate defaults or bounds already 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 names a specific verb and resource ('List commits on HEAD from the last N days'), states ordering ('newest first'), and scopes the operation to a recency window plus optional author/path filters. It distinguishes itself functionally from broader siblings like commit_search by pinning the window to HEAD and N days, though it never names an alternative tool explicitly.

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

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

Usage is implied rather than stated: an agent can infer 'use this for recent activity in a time window' from the description, but there is no explicit when-to-use/when-not guidance and no reference to the sibling commit_search, which is the obvious overlap. Adequate but leaves routing to inference.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description is free to add the behavior that actually matters: how the ref range resolves by default and what happens when no tag exists. It does not mention pagination or size limits on potentially large commit ranges, which is the remaining gap.

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

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

Three sentences, tightly front-loaded with the core action and output modes, then the defaulting rule, then the concrete use case. Every sentence earns its place with no filler.

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

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

An output schema exists, so return structure needs no explanation, and all four parameters are schema-documented. The description covers defaults, modes, and the release-drafting workflow; only edge cases like empty ranges or oversized histories are unaddressed.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantics the schema lacks: the default resolution rule for 'from' (latest tag before 'to', else all commits up to 'to'), which is not expressed in the schema's parameter descriptions. It also clarifies the practical role of 'to' for existing releases.

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 (group commits between two refs into a release-notes draft) with the grouping axis (conventional-commit type) and both output modes. This is clearly separable from siblings like commit_search, compare_refs, and list_tags at a glance.

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 the key usage path: defaulting behavior of 'from', the no-tag fallback, and the specific case of drafting notes for an existing release by passing its tag as 'to', with a pointer to list_tags. It does not explicitly say when to prefer compare_refs or commit_search over this tool, so it stops short of full alternative 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 already declare readOnly/idempotent/non-destructive, so safety is covered. The description adds genuine behavioral context beyond that: merge commits are excluded, base is the ranking reference ('changed and broke on base'), and the companion signal means forgotten tests/config/callers. It stops short of describing pagination or output ordering.

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?

A single front-loaded sentence that compacts three analytical facets plus an exclusion rule. It is dense but every clause earns its place; the length is justified by the composite nature of the tool.

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

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

For a composite analysis tool with an output schema, the description covers what the briefing contains and the one notable filtering rule (merge commits excluded). An agent has everything needed to decide to call it and interpret the result.

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 rich per-parameter descriptions, so the schema carries the load. The description only loosely alludes to base/head semantics via 'base..head' and reviewer half-life concept, adding little beyond the structured fields. 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 names a specific artifact ('Review briefing for the changes in base..head') and then enumerates its three concrete outputs: ranked changed files, missing co-change companions, and suggested reviewers. This is precise enough to distinguish it from the narrower point tools like file_hotspots or change_coupling even though it doesn't name them.

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

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

It clearly frames the scenario ('e.g. a branch or pull request'), so an agent knows this is for pre-merge review of a diff range. It gives no explicit when-not or named alternative to pick instead, which keeps it below a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered. The description still adds behavior not captured there: result ordering (oldest first) and the inclusion of per-branch merge status against HEAD.

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?

A single sentence with no filler; the stale-threshold filter is front-loaded, followed by ordering and output content. Nothing is repeated or 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?

With an output schema present and full annotation coverage, the description need not explain return values, and it correctly focuses on filter and ordering semantics. Minor gaps remain around default-repo behavior and remote-branch handling, but those are covered in the schema.

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

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

Schema description coverage is 100% and every parameter (days, repo, limit, mergedOnly, includeRemote) is documented in-schema with defaults and bounds. The description restates the days threshold and the merged-into-HEAD condition, which loosely maps to days and mergedOnly, but adds no syntax or format detail beyond the schema. 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 (list), resource (branches), and a precise filter (latest commit at least N days old), plus the ordering (oldest first) and an output dimension (merged into HEAD). It is clearly distinguishable in practice from siblings like list_tags or recent_activity, though it never names an alternative to anchor that distinction.

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

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

There is no explicit when-to-use statement, no prerequisites, and no named alternative among the many siblings. The only usage signal is indirect, via mergedOnly's schema note about 'safe cleanup candidates,' which implies branch-pruning intent but leaves the agent to infer when this beats compare_refs or recent_activity.

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