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

Annotations only give readOnlyHint=false and openWorldHint=false; the description goes well beyond that, disclosing that the path is validated as a git repo at registration time, that nothing is cloned or fetched, that mirror-backed projects surface in list_repos before first read, and that re-registration preserves the existing freshness policy. These are exactly the behavioral traits an agent needs before calling.

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 action is front-loaded, followed by conditional behavior, side-effect exclusions, and re-registration semantics in four tight sentences. No filler and no repetition of schema or annotation content.

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

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

For a zero-required-param, two-parameter registration tool with no output schema, the description covers validation timing, side effects (no clone/fetch), visibility effects, idempotence, and alternative tools. An agent has everything needed to invoke it correctly and to route elsewhere when cloning is actually wanted.

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 meaning beyond the schema: it explains what selecting local_path changes (reads use that clone rather than a mirror) and that the path is validated here, while the schema only says 'Path to an existing clone'. The project parameter's default behavior is left to the schema, which already covers it.

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

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

Opens with a specific verb+resource ('Register a project with this server') and immediately differentiates the two registration modes: local_path clone-backed vs. mirror-backed. The distinction from siblings (sync_repo, list_repos) is made explicit in the body, so an agent can place this tool 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?

States precisely when to supply local_path (read from an existing clone instead of a server-side mirror) and what happens without it (mirror-backed registration). It names the alternative for fetching ('use sync_repo for that, or simply read the project') and the update semantics for an already-registered project, leaving nothing 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?

With annotations only covering read-only/open-world hints, the description carries real behavioral weight: binary files are refused, out-of-range lines are clamped and reported rather than erroring, `max_lines` caps output, and the result reports the blamed `commit` and `synced_at`. This is exactly the extra context annotations don't provide.

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

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

The core purpose and output row shape are front-loaded, and each subsequent sentence (clamping, max_lines, binary refusal, input modes) earns its place. It is dense and runs long, but no sentence 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?

With no output schema, the description steps up to describe the return shape (commit, author, date, line range, then numbered lines) plus the reported `commit`/`synced_at`. Combined with the documented input modes and edge-case behavior, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning beyond the schema: the clamping/reporting behavior for `lines`, the precedence of a URL anchor over `lines`, and the interaction where `url` replaces ref/path/lines. It stops short of 5 only because the schema already documents formats.

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 — showing per-line last-touch authorship of a file at a ref — and pins it to `git blame --porcelain`. It is clearly distinguishable from siblings like `log`, `diff_file`, and `get_file` by its line-level authorship semantics and 'without a working tree' framing.

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 invocation context: default ref is the default branch, and you supply either `url` (with `#L12-20` anchor narrowing) or `ref`+`path`. However, it never explicitly contrasts when to choose this over `log`, `pickaxe`, or `diff_file`, 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 readOnlyHint=true, so safety is covered; the description adds non-obvious behaviour instead: it never returns a patch because branch diffs are unbounded, the file list is capped by `max_files` and a capped answer is labelled as such, the `merge_base` used is printed, and both resolved commits plus `synced_at` appear in the result. These are real operational traits an agent cannot get from the annotations.

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

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

Front-loaded with the core operation and output format before the caveats, and essentially every sentence carries information. It is a dense single paragraph with several interleaved concerns (capping, rename narrowing, no-history case), which costs some scannability but no obvious filler.

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

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

There is no output schema, so the description must carry the return contract — and it does: per-file status letters (`A`/`M`/`D`/`R091 old -> new`), ± counts, `binary`, printed `merge_base`, resolved commits and `synced_at`. Combined with the cap semantics and sibling routing, an agent has everything needed to call and interpret this 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%, so the baseline is 3; the description earns an extra point by explaining consequences the schema only hints at — that narrowing with `path` can turn a rename into a delete plus an add, and that a `merge_base="none"` result signals unrelated histories. The `merge_base` toggle is largely restated from the schema, keeping this short of a 5.

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 precise verb and resource — summarise what changed on `to` since it split from `from` — and pins down the exact git operation (`git diff <merge-base> <to>`) and output shape (one row per file with status letter and ± counts). It also differentiates itself from the sibling `diff_file`, so an agent can pick between them without opening either 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 routes the agent: use `diff_file` for a single file's patch, and pass a printed `merge_base` as `from` to get the branch view of it. It also states the conditions that change behaviour (`merge_base: false` for the raw two-dot diff, no shared history ⇒ two-dot with `merge_base="none"`), leaving nothing 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?

With annotations only covering readOnly/openWorld, the description adds substantial behavioral detail: path scoping is applied before git runs, rename detection is narrowed so renames read as add/delete, unchanged files yield no diff, absent files are reported not found, and binary files are refused because git emits no patch. These are exactly the edge cases an agent must anticipate.

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 first sentence gives purpose and command form, and the remaining sentences each carry an edge case rather than filler. It is dense but slightly long, with some detail (e.g. restating context default) that the schema already supplies.

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, yet the description explains the meaningful result states (patch, empty diff, not-found, binary refusal) and the safety profile is covered by annotations. An agent has everything needed to call it correctly across the 6-param surface.

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 meaning to `from`/`to` (raw two-dot diff; merge_base from `compare`) and to how `context` and `max_bytes` shape the patch. The context default/range restates the schema, but the ref semantics elevate it above the baseline.

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

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

States a precise verb+resource ('The unified diff of one file between two refs') plus the exact underlying command, and distinguishes the scope from siblings like compare and get_file. An agent can tell it produces a patch for a single named path rather than a ref comparison or file read.

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

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

Gives clear operative guidance: pass a `merge_base` printed by `compare` as `from` for a per-file branch view, and explains the consequences of path scoping (narrowed rename detection). It references the `compare` sibling but does not explicitly say when to prefer this over `compare`/`get_file` for other tasks.

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

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

Annotations only declare readOnlyHint and openWorldHint, so the description adds real behavioral context: merge commits report merge="true" with no file list, patches are capped and marked when cut, and the result states the resolved commit and synced_at. No contradictions with the read-only 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?

Dense but front-loaded, leading with what the commit read returns before the parameter guidance and merge caveat. Every sentence carries information, though the run-on style packs several distinct ideas into long clauses.

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

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

With no output schema, the description correctly carries the burden of describing the return shape (commit metadata, file list with status letters, merge marker, synced_at). It is nearly complete for the tool's complexity, with only minor gaps such as pagination or error behavior.

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 still adds meaning beyond the schema: rev accepts full/abbreviated sha or branch/tag, url must have a GITLAB_HOST host, and patch appends a unified diff capped by max_bytes with cut patches flagged.

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 (read) and resource (one commit) and enumerates exactly what is returned: sha, parents, author/committer with dates, message, and changed files with status letters and line counts. This clearly differentiates it from list-oriented siblings like log and list_tree.

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?

Explains the url-vs-rev choice ("Give either `url` ... or `rev`") and points to the alternative for merges ("compare a parent with the commit to see what it brought in"). It names the sibling compare implicitly but does not spell out general when-not-to-use cases beyond merges.

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 carry readOnlyHint=true and openWorldHint=false; the description goes well beyond that by disclosing the mirror-on-first-use / refresh-when-stale model, the add_repo clone path, the stale-cache fallback when refresh fails, and that the result reports the resolved commit and sync time. This is exactly the extra behavioral context the annotations cannot supply, and it is consistent with openWorldHint=false.

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 scope constraint is front-loaded, and each subsequent sentence carries distinct information (addressing modes, the mirror lifecycle, the failure fallback). A few sentences are dense and could be split, but there is no filler or 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?

Given no output schema, the description usefully sketches the return payload (resolved commit, last sync time) and the degraded-refresh case, and it covers all five parameters' roles. A fully 5 definition might specify the content/encoding shape or the error behaviour when neither url nor ref+path is supplied, but the critical calling information is present.

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 genuine semantics: the `url` alternative to `ref`+`path`, that a `#L12-20` line anchor is honoured, that the URL usually overrides project, and that project falls back to GITLAB_DEFAULT_PROJECT or the URL's project. It does not explain max_bytes interaction 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?

States a precise verb and resource ('Return the contents of a file at a given branch, tag, or commit') and adds the differentiator 'WITHOUT checking it out', which separates it from diff_file, list_tree, and get_commit. An agent can pick this tool out of the sibling list 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?

Gives a clear operative condition: 'Use this to inspect files on a branch other than the one currently checked out.' It also explains how to address the file (url vs ref+path) and when the local mirror versus your own registered clone is used. It does not name a sibling alternative 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.

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

Annotations only declare readOnlyHint/openWorldHint; the description adds substantial non-obvious behavior: results reflect a local copy as of `synced_at` (default ≤10 min old), newly created refs may be missing, staleness is undetectable, and on refresh failure the cached copy answers and the result flags the failure. That is exactly the kind of operational context structured fields cannot carry.

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

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

Front-loaded with purpose and output shape, then caveats in decreasing priority. Dense but almost every clause carries real information; the staleness/failure explanation is slightly verbose but justified given 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?

With no output schema, the description compensates by specifying the returned row fields (kind, short commit, name, tip subject) and the freshness/failure semantics. An agent has everything needed to call it and interpret results.

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

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

Schema description coverage is 100%, so all four parameters (kind, search, project, max_refs) are already documented in the schema. The description adds no syntax or default 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?

States a specific verb and resource ('List branch and/or tag names in a repository') plus the defining scope qualifier 'without cloning it into a working tree', which distinguishes it from file/tree siblings like list_tree and get_file. It even describes the row shape, so an agent knows exactly what comes back.

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 routes the agent to the sibling alternative: 'Use `resolve_ref` to check one specific ref, which does refresh on a miss.' This gives a clear when-to-prefer-the-other-tool condition rather than leaving the choice 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?

With annotations already declaring readOnlyHint and openWorldHint=false, the description adds substantial operational context: freshness semantics (ttl/always/manual), the fact that manual entries never self-refresh, that unsupported clone_strategy makes a project refuse to be read until re-cloned, and that synced_at may be 'unknown'. This is behavior an agent cannot infer from the annotations.

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

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

The output-column enumeration is dense but front-loaded with purpose, and each column row earns its place given there is no output schema. Slightly long, but no clearly redundant sentences.

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

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

There is no output schema, so the description compensates by documenting the full row layout (path, source, freshness, ttl, clone_strategy, present, local_path, synced_at). Combined with the freshness and re-clone caveats, it is complete enough for an agent to call and interpret the result correctly.

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

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

The tool takes zero parameters, so the schema carries no semantic burden; the baseline for a 0-param tool is 4. The description instead spends its budget on return-shape semantics, which is appropriate but not a parameter concern.

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 ('List the repositories this server knows about') and immediately scopes it with the freshness policy and sync state, which no sibling does. It also contrasts with add_repo and sync_repo, letting an agent place it among the 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?

Gives clear routing context: add_repo registers a mirror-backed project before first use or points at an existing clone, and freshness=manual cases should be refreshed via sync_repo. There is no explicit 'use list_repos when X vs Y' statement, 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?

Annotations already declare readOnlyHint and openWorldHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: everything is answered from git with no file fetched, and a stale-cache fallback where the result flags a failed refresh. This is genuinely useful operational detail.

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 action and default depth, then parameter selection, then behavior. Every sentence carries information; the length is justified by the six parameters and caching nuance, though it is denser than strictly necessary.

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

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

With no output schema, the description carries the return-value burden, and it does explain that results carry sizes and repo-root-relative full paths. Ordering and pagination behavior beyond the max_entries default are not covered, leaving a minor gap for a listing 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%, so the baseline is 3. The description goes further by clarifying relationships the schema does not: url replaces ref/path/project, names are full paths relative to repo root, and size is in bytes. That adds meaning 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 uses a specific verb (list) on a specific resource (files and subdirectories at a ref) and states scope precisely: 'one level deep by default; set recursive to walk the whole subtree.' This clearly separates it from read-oriented siblings like get_file and log without needing to 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 gives concrete selection guidance: use url OR ref (plus optional path), and use recursive only when you want the whole subtree. The remark that sizes let you 'tell a small config from a bundle before reading it' implies using this before get_file. It stops short of explicit when-not or naming alternative 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?

With readOnlyHint/openWorldHint already covering the safety profile, the description adds real behavioral context: no working-tree clone, ref resolution before the walk, the result reporting the walked commit and `synced_at`, truncation being disclosed rather than a fabricated total, and the rename termination behavior of `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?

Front-loaded with the core action and return shape, and every sentence carries information; the caustic details (rename stop, limit honesty) earn their place. It is dense, with several clauses packed per sentence, which slightly taxes readability but adds no filler.

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

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

There is no output schema, so the description supplies the return shape itself (commit, date, author, subject, `(merge)` marker) plus the `synced_at`/walked-commit metadata. Combined with 100% parameter coverage, an agent has everything needed to invoke and interpret this 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%, so the baseline is 3, but the description goes further: it gives the concrete `/-/commits/<ref>[/<path>]` link shape with a full example for `url`, notes `url` replaces `ref` and `path`, and explains the glob/rename semantics of `path` and the capping behavior of `limit`.

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 precise verb+resource ('List commits on a branch, tag, or commit'), names the git equivalent, and specifies ordering ('newest first') and the no-clone execution model. It is clearly distinguishable from siblings get_commit (what a single commit changed) and blame/list_tree.

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 routes to alternatives: 'Use `get_commit` on a row's full sha to see what it changed' and 'use `get_commit` when you need to see the rename itself.' It also states the two mutually exclusive input forms (either `url`, or `ref` and `path`) and their constraints.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered structurally. The description nonetheless adds real behavioral context: the host must be GITLAB_HOST, resolving may mirror the project on first use, and `resolve: false` avoids touching it. It does not describe the shape of the returned object (project/ref/path/line range are only implied), so it adds value but stops short of full behavioral disclosure.

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 transformation in the first clause, and every sentence carries non-redundant information (link types, refusals, host constraint, mirroring, plus the sibling hand-off). Sentences are long and clause-heavy, which costs some scannability but not correctness.

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, and the description compensates by naming what is extracted (project, ref, path, line range) and what happens on rejection. With the host/mirroring constraints and offline option covered, an agent has enough to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds meaning beyond the schema by explaining that refs containing slashes are resolved against the project's own refs, which clarifies the hard case the two schema lines only gesture at. It does not add syntax detail for the base url parameter, so it falls short of 5.

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 ('Turn a GitLab web link into the project, ref, path and line range') and enumerates exactly which URL shapes it handles. It distinguishes itself from siblings by naming get_file, list_tree, log, get_commit and blame and clarifying they accept a url directly, so an agent can route without opening schemas.

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

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

Gives explicit when-to-use ('for inspecting a link, not for reading') and when-not-to-use, plus an inbound filter: which GitLab link types are accepted versus refused ('merge request and other links are refused by name rather than guessed at'). It also states the host precondition and the offline escape hatch.

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 cover the safety profile (readOnlyHint=true, openWorldHint=false), and the description adds matching semantics (literal, case-insensitive, consistent with `search`), the ref default (repository default branch), result ordering (most recent first), and the relative cost versus `search`. These are concrete behavioral traits beyond the structured fields.

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 core behavior in the first clause, then layers return shape, matching semantics, cost/comparison to sibling, and argument defaults. Every sentence carries distinct information despite the length.

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

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

With no output schema, the description still specifies the row shape (`commit`, `date`, `author`, subject) and ordering, so an agent knows what comes back. Combined with the annotations and full schema coverage, nothing needed to invoke it 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 adds value by clarifying that matching is literal and case-insensitive consistent with `search`, which explains `case_sensitive`'s default behavior, and by restating ref/path semantics in workflow terms. It does not document `limit` or `project` beyond the schema, so it is not fully additive.

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 precise verb+resource: finding commits whose diff changed the occurrence count of a piece of text, with the git analogue (`git log -S`) and the user-facing question it answers. It explicitly distinguishes itself from the `search` sibling, so an agent can select between them without opening either schema.

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

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

Gives explicit when-to-use and the routing rule: use `search` to find where text is, use this to find when it appeared, and pair them. It also warns that this walks history and is slower, which is exactly the exclusion criterion an agent needs.

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

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

Beyond the annotations' destructiveHint=true, it discloses exactly what is destroyed (server-side mirror only; local clone never touched), that the request may be silently 'reported as ignored', and that mirror-backed forgetting is not permanent because the next read re-registers and re-clones. This is rich operational detail an agent cannot get from the annotations.

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

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

The core action is front-loaded in the first sentence, and every following clause carries a distinct behavioral fact (mirror scope, ignored request, re-registration, local→mirror revert). The dense em-dash constructions make it slightly heavier than necessary, but 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 mutation tool with no output schema, the description covers the important semantics: what gets deleted, what is immune, idempotency/reversibility. It does not mention permission or authentication requirements, which is the only notable 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 meaning beyond the schema: delete_mirror's effect is non-permanent (re-created on next read) and applies only to mirrors, while omitting it reverts a local registration to mirror-backed reading.

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 ('Forget a project's registration') and immediately clarifies the scope of what is and isn't removed, which no sibling tool covers. It doesn't explicitly name add_repo/list_repos as counterparts, so it is clear but not sibling-routed.

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 explains clearly what delete_mirror does and when forgetting is reversible versus how a local registration is switched back to mirror-backed reading, giving real context for choosing the flag. It stops short of an explicit when-to-use-this-instead-of alternative (e.g. add_repo, sync_repo).

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuinely non-derivable behavior: missing refs produce an error that 'lists similar names,' and a stale working copy is flagged so that 'a missing ref proves nothing.' That stale-data caveat is exactly the kind of context that prevents a wrong conclusion, though nothing is said about auth or rate limits.

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

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

Two sentences, front-loaded with what the tool returns before the usage advice, and every clause carries information. The final sentence is somewhat dense ('and it says so when the copy could not be refreshed') but still earns its place by qualifying the error semantics.

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 two-parameter read tool with no output schema, the description covers purpose, when to call it, the shape of the return value, and error behavior. With annotations handling the safety profile and the schema handling parameter docs, it is close to complete; only the absence of any mention of alternative ref-listing tools 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%, with the ref format and an example ('develop', 'fix/PROJ-7608') and the project path fallback to GITLAB_DEFAULT_PROJECT already documented in the schema. The description adds no syntax, format, or default information 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 ('resolve'), the resource ('a branch, tag, or revision'), and the exact output ('the full commit SHA it points at', plus a type label of branch/tag/commit). That scope clearly separates it from siblings like list_refs (enumerate) or get_commit (fetch metadata), so an agent can route correctly 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?

It gives an explicit use case: 'Use this to confirm a ref exists before reading files from it,' which tells the agent when this is the right call. It does not name an alternative or say when not to use it (e.g. vs. list_refs), so it stops short of full routing 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?

Beyond readOnlyHint/openWorldHint it discloses non-obvious behavior: literal matching with case-insensitive default, ref defaults to the default branch, a cold ref is fetched on miss, results report `commit` and `synced_at`, context is built by re-reading each file with a cap of 20 files per call, and max_matches caps rows while totals stay exact.

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 capability and the output shape before edge cases. It is dense but nearly every clause carries actionable detail; the ref/pathspec/context sentences could be tightened into a list for faster scanning.

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?

Nine parameters and no output schema, yet the description effectively supplies one (grouping, line format, header fields, exact totals). Limits, defaults, and error-ish behavior (empty path match, ref fetch on miss) are all covered, so an agent can call it correctly without further information.

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 already 100%, so baseline is 3; the description earns an extra point by explaining consequences the schema only hints at — that `files`/`count` make git skip emitting matched lines so totals stay exact, and why `context` must be rendered internally. It repeats the pathspec `**` note verbatim from the schema, which slightly dilutes the added value.

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 a whole file tree at a branch, tag, or commit — git grep') and adds the key scoping fact ('without cloning it into a working tree'), which separates it from get_file, list_tree, and blame. The output shape (path then 'line: text' grouped by file) further pins down what it returns.

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 routes to `output: files|count` when counts matter and to `pickaxe` when the question is *when* text appeared, and warns that a nonexistent path silently returns nothing. It stops short of naming get_file or log as alternatives for the reverse cases, so it's clear but not exhaustive.

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

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

Adds rich behavioral detail beyond the annotations: a mirror-backed project is cloned if its mirror is missing, a local clone is fetched from its own remote, and failures surface as errors rather than cached answers. This meaningfully explains the readOnlyHint=false mutating behavior and is exactly the kind of context annotations cannot carry.

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 core action and keeps to three sentences, each carrying distinct information. Slightly dense and the final clause is somewhat circular ('this call exists to fetch'), but there is no wasted 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 mutation-flagged, open-world single-parameter tool with no output schema, the description covers trigger conditions, cache/failure behavior, and clone vs. mirror handling. It is close to complete; only return-value expectations remain implicit, which is acceptable given the tool's purpose.

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 the single `project` parameter (including its default) is fully documented in the schema. The description adds behavioral context but no syntax or format detail beyond what the schema already provides, so the baseline 3 applies.

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

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

States a specific verb and resource ('Fetch a project immediately, ignoring its freshness policy') and immediately contrasts the behavior with a cached read. An agent can distinguish this from read siblings like get_file or list_refs without opening either 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 names the conditions that select this tool: refreshing a project whose policy is `manual` and checking for new refs without waiting for the TTL. That is clear when-to-use guidance, though it routes by condition rather than naming a specific sibling alternative.

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