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

No annotations are provided, so the description carries the full burden. It implies a passive read ('Returns', 'inspect') and the zero-parameter schema means there is no destructive surface, but it never explicitly states read-only behavior, side effects, or that metrics are in-memory and reset per process.

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 short sentences, front-loaded with the returned fields. The second sentence's 'verify cache hits' slightly overlaps with 'inspect caching performance', but the text is otherwise tight and waste-free.

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

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

With no output schema and no annotations, the description usefully enumerates the returned metrics, which is the key information needed. It is adequate for a trivial zero-parameter read tool, though a note on read-only/side-effect-free behavior would close the 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?

The tool takes zero parameters, so the baseline of 4 applies. There is nothing for the description to disambiguate, and it correctly does not invent parameter detail.

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

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

States a specific verb and resource ('Returns in-memory cache metrics') and enumerates the exact metrics returned (hits, misses, entry count, hit rate). This is unambiguous and clearly distinct from the git-oriented sibling tools.

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

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

Gives clear usage context: 'Use to inspect caching performance and verify cache hits.' No alternatives or when-not-to-use guidance is offered, but none of the siblings overlap with a cache-metrics tool, so the omission is low-impact.

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?

No annotations are provided, so the description carries the burden. It implies a read-only query ('finds', 'reports') and enumerates the return fields, but never explicitly states it is side-effect-free, nor mentions auth, rate limits, or error behavior for invalid refs.

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 compact sentences, front-loaded with the core operation and followed by usage and return values. Every sentence contributes, though the trailing return-field list slightly overlaps what a caller might infer.

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, enumerating mergeBaseSha/aheadBy/behindBy/status is genuinely useful return-value context. For a straightforward read-only query tool with fully documented params, this is nearly complete; only explicit read-only/error behavior 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%, with base/head/repo/owner all documented in the schema. The description adds no syntax or format detail (e.g. SHA vs branch vs tag nuances) beyond what the schema already conveys, so the baseline 3 holds.

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 (finds) and resource (common ancestor commit / merge base between two refs), plus the extra ahead/behind reporting that distinguishes it from a pure ancestry check like is_ancestor. However, it never names the closest sibling (is_ancestor) explicitly, leaving differentiation to inference.

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?

'Use to check branch divergence before merging or comparing histories' gives a clear when-to-use context. It does not name alternatives (e.g. is_ancestor) or state when NOT to use this tool, so it stops short of a 5.

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

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

With no annotations the description carries the full burden, and it does real work: it discloses that only *merged* PRs are returned and enumerates the return contract (number, title, URL, merged date, author). It does not mention auth requirements, rate limits, or what happens for a SHA with no associated PR.

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

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

Three short sentences, front-loaded with the action and scope, then usage, then return shape. No filler or restatement of the name.

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

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

No output schema exists, but the description compensates by listing the returned fields, and the merged-only filter is stated. Missing only edge-case behavior (empty result, invalid SHA handling) for a fully complete picture.

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 owner/repo/sha are already documented at the field level; the description only implies that the SHA may be a commit, and the schema actually broadens it to 'branch, or tag'. Baseline 3 for high-coverage schemas is correct with no added syntax or format guidance.

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: 'Finds merged pull requests associated with a commit SHA.' The merged-only constraint and the SHA linkage make it instantly distinguishable from the plumbing siblings (find_merge_base, resolve_ref, get_blame).

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?

'Use to discover original PR discussions, reviews, and context for an existing commit' gives a clear motivating scenario for when to reach for this tool. It stops short of naming alternatives or stating exclusions, which the very different sibling set makes less necessary.

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

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

With no annotations, the description carries the full behavioral burden; it usefully discloses the return shape (ranges of lines with commit, author, and PR metadata) and that start_line/end_line slice the result. It says nothing about auth requirements, behavior on large or binary files, or limits, which matters for a tool with no annotations.

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

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

Three tight sentences: purpose, use case, return shape plus slicing hint, all front-loaded with zero filler. Each sentence carries distinct information, and the output-shape sentence is especially valuable given there is no output schema.

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 blame tool with no output schema and fully documented params, the description covers purpose, trigger, and return structure, which is nearly enough to call it correctly. It omits edge-case behavior (large files, renames/binary content) and any auth or limit context.

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

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

Schema description coverage is 100%, so all six parameters are documented in the schema; the baseline of 3 applies. The description only reinforces the start_line/end_line slicing and implies ref semantics via 'at a commit or ref,' adding little 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: 'Returns line-by-line git blame annotations for a file at a commit or ref,' which is clearly distinct from siblings like get_path_history or get_diff. It never explicitly contrasts itself with those siblings, so an agent must infer the distinction from the resource type alone.

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

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

'Use to identify who changed specific lines, when, in which commit, and via which PR' gives a concrete task-level trigger. No exclusions or named alternatives are offered, so it stops short of full when/when-not guidance.

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

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

No annotations exist, so the description carries the burden and does meaningful work: it discloses truncation behavior and the default cap (60KB), plus the mitigation (narrow with paths). A read-only nature is implied but not stated, and no auth/rate-limit context is given.

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, fully front-loaded: purpose first, then actionable truncation guidance. Every clause earns its place with no redundancy.

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

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

For a read-only diff tool with a fully documented schema and no output schema, the description covers purpose, scope, and the key behavioral gotcha (truncation). It lacks return-format framing (unified diff text) beyond naming it, but this is minor.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters clearly. The description reinforces the truncation parameter and paths restriction but adds no syntax or format detail beyond the schema. Baseline 3 is 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 (returns) and resource (unified git diff between two refs), names the scope (optionally restricted to file paths), and distinguishes its use case (inspect code changes without cloning) from siblings like get_file_at_ref or list_changed_files.

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 to inspect code changes without cloning') but does not explicitly name alternative siblings or state when not to use it, e.g. versus list_changed_files for a file list only.

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

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

With no annotations, the description carries the full load, and it discloses hard behavioral limits the schema cannot express: binary files are rejected and files over 1 MB are rejected. It leaves the return shape and error/pagination behavior unstated, which keeps 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?

Three short sentences, front-loaded with the core action, followed by usage then constraints. Every sentence adds information and nothing is repeated.

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 read tool with no annotations and no output schema, the description covers purpose, when to use it, and the two failure limits that matter. The main remaining gap is what the returned content looks like (raw text? truncated?), but this is minor.

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

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

Schema description coverage is 100%, so every parameter (owner, repo, path, ref, start_line, end_line) is already documented at the source. The description only adds a light hint to narrow with start_line/end_line and confirms the ref default, which is marginal 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 ('Retrieves') and resource ('file content at a specific ref or commit') with a scope qualifier ('optional line slicing'). It implicitly separates itself from siblings like get_diff or get_blame by framing the job as reading file content, though it never names an alternative 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?

'Use to inspect historical code without cloning' gives clear context for when this tool applies, and the binary/1 MB rejection plus 'Narrow with start_line and end_line' implicitly states when-not/refinement conditions. No explicit routing to sibling tools such as get_path_history or get_blame 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?

With no annotations, the description carries the full burden and does a fair job: it discloses the return shape (SHA, author, date, headline), the hard cap of 100 commits, the default of 20, and how to narrow results. It does not state pagination/ordering behavior or permissions, but for a read-only listing the disclosure is solid.

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

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

Four short sentences, each doing distinct work: purpose, use case, return values, limits/filters. Scope and output are front-loaded, and nothing is redundant 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?

No output schema exists, so the description correctly supplies the return fields and the result cap. Combined with the fully covered input schema, an agent has what it needs to call and interpret the tool; only ordering/pagination nuances are unstated.

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 ref, path, limit, since, and until with types and defaults. The description restates the cap/default and groups since/until/limit as narrowing controls, which is mildly useful but largely duplicative of 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?

States a specific verb and resource: 'Lists commits modifying a specific file or directory up to a ref.' That clearly separates it from siblings like get_diff or get_blame, which operate at other granularities. It stops short of explicitly naming such siblings, so 4 rather than 5.

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

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

'Use to trace when a path was touched or refactored' gives a concrete scenario, and 'Narrow with since, until, or limit' tells the agent how to scope a call. No explicit when-not or named alternative (e.g. get_blame for per-line authorship) is offered, 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?

With no annotations, the description carries the full burden. It usefully discloses the return shape (boolean plus explanation) and that no clone is needed, but says nothing about authentication requirements, rate limits, or error behavior for unresolvable refs.

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

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

Three short sentences in a logical order: what it computes, when to use it, what it returns. No filler or 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 four-parameter read tool with no annotations and no output schema, the description covers purpose, a usage scenario, and the return value. Minor gaps remain around failure modes and how branch/tag names are resolved, but nothing essential to calling it 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 owner, repo, ancestor, and descendant are already documented, including that refs may be SHAs, branches, or tags. The description adds no 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 states a precise verb and resource: it determines ancestry between two named commits, and even clarifies that 'ancestor' and 'descendant' are the two inputs. It does not differentiate from the closest sibling, find_merge_base, which answers a related graph question.

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 a concrete use case — verifying whether a fix or feature branch is contained in another branch without cloning — which tells the agent when this tool is appropriate. It offers no explicit exclusions or alternatives, so the agent must infer how it differs from find_merge_base or resolve_ref.

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

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

With no annotations, the description carries the full burden and does disclose a meaningful behavioral trait: a hard 500-file cap and the escape hatch (path_prefix). It does not explain what happens at the cap (truncation vs. error) or any auth requirements, so it falls 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 short sentences, each earning its place: purpose, usage context, and limit workaround. The defining scope (two refs) is front-loaded and nothing is 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?

For a read-only listing tool with full schema coverage and no output schema, the description covers what is returned at a high level (changed files plus change statistics) and the cap behavior. The residual gap is only the exact response shape and cap-handling semantics.

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 base, head, owner, repo, and path_prefix are already documented. The description reinforces the path_prefix narrowing behavior but adds no syntax, default, or format detail beyond the schema – baseline 3.

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

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

The description states a specific verb (lists), resource (files), and scope (between two git refs, modified/added/deleted, with change statistics). This makes it clearly distinguishable from get_diff (patch content) and get_path_history (single-path history) without naming them 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?

"Use to survey changes across commits or branches" gives clear intended context, and the path_prefix hint points at narrowing scope. It stops short of naming a sibling or a when-not condition, so it is clear but not fully 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?

No annotations are provided, so the description carries the full burden. It does disclose useful traits: the return shape ({sha, refType}) and the 'fast and cached' performance profile. However, it says nothing about failure modes (invalid/ambiguous ref), required permissions for private repos, or cache staleness, leaving meaningful behavioral gaps for an annotation-free tool.

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

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

Three short sentences, front-loaded with the core operation, followed by usage and return shape. Every sentence earns its place with no 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?

Though no output schema exists, the description compensates by declaring the returned fields. Combined with the parameter schema being fully documented, an agent has enough to invoke it correctly; only error/permission behavior is 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 description coverage is 100%, and each of the three parameters (owner, repo, ref) is already documented in the schema with the same wording the description implies. The description adds only the accepted ref formats (branch/tag/partial SHA), which is marginal beyond the schema baseline of 3.

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

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

States a specific verb (resolve) and resource (git reference) along with the exact transformation performed: branch/tag/partial SHA to full 40-character commit SHA. The output is also defined, so an agent can distinguish it from siblings like get_file_at_ref or find_merge_base 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?

Explicitly says to use it 'before queries when you need the canonical immutable commit identifier', which gives a clear triggering context. It does not name alternative tools or state when-not to use it, so it falls short of a 5.

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