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

With only readOnlyHint=true in annotations, the description adds substantial context: what statistics are pulled, how reclaimable bytes are computed from expired-but-kept and old artifacts, and that injected rows skip the live pull. It stops short of noting auth needs or rate limits, but for a read-only analysis tool this is rich 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-loads the purpose and scoping before the Args block, and every section is scannable. Given 0% schema coverage the param detail is justified, though the Returns block is slightly verbose since the keys mostly restate the ranking concepts.

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?

Five parameters with zero schema descriptions and no output schema, yet the description documents all inputs and the return shape (projectsEvaluated, totalReclaimableBytes, per-project breakdown). Nothing an agent needs to call 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 description coverage is 0% (titles only), so the description carries the full burden, and it does: it defines old_artifact_days, limit, target, and the precise shapes of the two injection parameters ({path, repoBytes, artifactsBytes} and the per-project artifact map). This is far more than the schema provides.

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 ('Rank projects by storage; estimate reclaimable artifact bytes') and frames it as the 'flagship storage RCA'. An agent can distinguish it from siblings like list_artifacts, delete_artifacts, and stale_work_audit 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?

Explicitly explains the two operating modes: pass 'projects'/'artifacts_by_project' for pure analysis, or a 'target' to pull live. That is clear operational guidance, but it does not name which sibling to prefer for adjacent storage tasks, 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 flag destructiveHint=true and non-idempotent, but the description adds genuinely new behavior: it performs an internal read so priorState captures the pre-cancel status, the action is irreversible with no undo, and dry_run provides a preview path. These are traits an agent cannot infer from the annotation block alone.

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

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

Front-loads the verb, the write/risk tag, and the irreversibility warning before the structured Args block. Every sentence carries information; nothing is redundant.

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 conveys the key outcome (priorState capture, irreversible stop) and the dry-run escape hatch, which is sufficient for a mutation tool whose annotations cover the safety profile. It omits permission/authorization requirements and what the cancel response returns, leaving a small gap.

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

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

Schema description coverage is 0%, so the description carries the full burden and does so for all four parameters: project (id or full path), pipeline (id, sourced from list_pipelines), dry_run, and target (server target from config, omit for default). Only minor detail is missing (e.g. exact id format), keeping it at 4 rather than 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+resource ('Cancel a running pipeline') and is instantly distinguishable from siblings like retry_pipeline, list_pipelines, and pipeline_detail. The [WRITE][risk=medium] tag further disambiguates the operation class.

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 operational context: how to obtain the pipeline id ('from list_pipelines') and that dry_run=True previews before committing. It does not explicitly state when-not to use it versus alternatives such as retry_pipeline, so it falls just 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 already declare readOnlyHint=true, so the safety profile is covered. The description adds genuinely useful behavior beyond that: a failing sub-call degrades to a partial summary with an 'errors' list instead of crashing, which tells the agent to expect possible partial results. It does not discuss 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?

Three short lines, front-loaded with the '[READ]' tag and the aggregation scope, followed by the resilience note and the arg. Every line carries information; the 'Args:' block is standard formatting rather than padding.

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

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

With no output schema, the description correctly steps in to say what the summary contains (version, token identity, projects, runners) and how failures surface (errors list). For a single-optional-parameter read tool, this is close to complete, though it could note result granularity briefly.

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 0%, so the description must carry the single parameter — and it does: 'target: Server target name from config; omit for the default.' That fully explains both the meaning and the default behavior, compensating for the empty 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+resource ('One-shot summary') and enumerates exactly what is aggregated: version, token identity, projects, runners. This implicitly separates it from granular siblings like server_version, list_projects, and list_runners, 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?

'One-shot summary' implies the intended context (use when you want a broad snapshot rather than individual list calls), and the '[READ]' tag signals a safe query. However, there is no explicit when-to-use vs. when-not statement or named alternative for deeper inspection.

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 '[READ]' merely repeats that safety profile. The description does add a genuinely useful behavioral detail — that the result reflects the token's identity as seen by the API (a scope probe). It says nothing about error behavior for invalid/expired tokens, so against annotation coverage a 3 is appropriate.

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 '[READ]' tag and core purpose in one clause, followed by a compact Args block. No filler sentences, though the tag duplicates the annotation rather than adding new information.

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 single-optional-param read tool with no output schema, the description covers identity semantics and the param's meaning. It could say a bit more about the returned identity format, but nothing an agent needs to call 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 description coverage is 0%, so the description must carry the single parameter — and it does, explaining that 'target' is a server target name from config and that omitting it uses the default. That meaning is not available from the bare schema, so it compensates well for the coverage gap.

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 verb: returning the token's identity, i.e. 'who the API sees you as'. This is self-evidently distinct from the pipeline/runner/project listing siblings. It stops short of explicitly naming how it relates to any sibling, so it lands at 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?

The parenthetical '(scope probe)' implies the tool is used to verify the token's permissions/scope, which is useful implied usage. However, it never states when to reach for this versus an auth/health sibling, nor any exclusion conditions. Usage is implied but not spelled out.

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?

Goes well beyond the annotations: declares IRREVERSIBLE with no undo, explains it reads the artifact inventory first so priorState records file count and bytes destroyed, and explains that the bulk delete is refused when inventory is unreadable unless explicitly acknowledged. This is exactly the contextual detail destructiveHint alone cannot convey.

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

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

Risk markers and the irreversibility warning are front-loaded, and the Args block is easy to scan. It is somewhat long, but nearly every sentence adds a distinct constraint or safety behavior rather than restating the 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 high-risk destructive tool with no output schema, the description covers safety, previewability, the inventory/priorState behavior, and all five parameters including the acknowledgment escape hatch. Nothing needed to invoke it safely 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 0%, so the description carries the full burden and does: project is id-or-path, older_than_days=0 means the server's bulk delete of all eligible artifacts, dry_run previews, acknowledge_unknown_inventory has a clear condition and exclusion, target is a config name with a default. Every parameter gains meaning beyond the bare schema titles.

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 (delete) plus resource (a project's artifacts) with explicit scope qualifiers (all, or older than N days). The [WRITE][risk=high] tag and the sibling list_artifacts/artifact_storage_bloat_analysis make the destructive-vs-read distinction clear 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?

States when to use each mode: pass dry_run=True to preview, use older_than_days to limit deletion by age. It also states when acknowledge_unknown_inventory applies and when it never applies. It doesn't explicitly route the agent to a read alternative like list_artifacts, 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?

With only readOnlyHint provided, the description carries the behavioral load and does so well: it details the returned fields, explains that 'truncated' means earlier lines were dropped (so the first error may be above the window), and warns about 'charsTruncated' hitting a byte ceiling. This is rich disclosure beyond the annotation.

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

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

Front-loaded with a [READ] tag and one-line purpose, then return shape, then truncation caveats, then Args. The return-field enumeration is dense but justified given no output schema; overall each block earns its place.

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

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

Given no output schema, the description covers purpose, all params, and the truncation semantics that govern correct interpretation. It omits error behavior (e.g., unknown job/project) but is otherwise sufficient to call and interpret the 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 0%, so the description must compensate, and it documents all four params: project (id or full path), job (id from pipeline_jobs), tail_lines (trailing line count/default 60), and target (server target name, omit for default). Each adds meaning beyond the bare schema types.

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

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

States a specific verb+resource — 'the tail of one job's log/trace' — and frames its use case ('where the failure explains itself'). It distinguishes itself by noting the job id comes 'from pipeline_jobs', but does not explicitly contrast with sibling RCA tools like pipeline_failure_rca.

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 situational context (diagnosing job failures) and even an actionable rule: 'raise tail_lines before concluding a root cause' if truncated. However, it names no alternative tool or when-not-to-use condition, so the agent must infer routing.

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

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

Beyond readOnlyHint=true, the description discloses non-obvious behavior: totals count every artifact found even when rows are truncated, 'jobScanTruncated' means older jobs are excluded and totals are a lower bound, and it names the specific return fields. This is far more than the annotation provides.

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?

Purpose and the critical truncation/lower-bound caveats are front-loaded before the Args block, and every sentence conveys operative information given the empty schema descriptions.

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 beyond read-only, the description compensates by explaining the returned counters and truncation flags as well as every argument. 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 description coverage is 0%, so the description carries the full burden and does: project accepts an id or full path with two format examples, limit is max rows with default 500, and target is a named server config that can be omitted for the default.

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 first line states a specific verb and resource ('[READ] A project's artifact inventory: files, sizes, expiry'), and the second sentence ties it to the delete_artifacts workflow, making it distinguishable from siblings like artifact_storage_bloat_analysis.

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 tool's role by reporting 'the delete_artifacts candidates', implicitly routing an agent that wants cleanup targets here. It lacks an explicit when-not-use statement or a direct named alternative, 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?

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description goes beyond that by disclosing the truncation signal ('the result carries truncated when the server had more') and the result fields, which is meaningful behavioral context for a list operation.

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 [READ] marker, one-line summary, then a compact Args block. Every line carries information; there is no filler, though the summary could be tightened into an explicit verb.

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 supplies the key return fields and truncation behavior, and documents all three parameters. It stops short of explaining how to retrieve the remaining rows once truncated, which is the one real gap for a capped list 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 description coverage is 0%, so the description carries the full parameter burden and largely meets it: project is 'id or full path', limit carries default/cap/truncation behavior, and target explains config-server selection. The only ambiguity is the 'default 100, capped at 99' wording, which reads as inconsistent.

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 resource (branches) and states the fields returned (last-commit date, protected flag), with a [READ] tag reinforcing the operation type. It does not, however, distinguish itself from the sibling list_protected_branches, leaving the agent to infer the difference.

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 guidance and no mention of the sibling list_protected_branches, which returns an overlapping resource. The only routing hint is 'omit for the default' on target, which is parameter detail rather than tool-selection 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?

readOnlyHint already covers the safety profile, and the description adds real operational context beyond it: the limit cap (max 99), the 'truncated' flag that signals the server had more rows, and the note that platform-specific state words are translated. It does not describe the shape of returned rows, but the annotations carry the main burden.

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 a bracketed read marker and a one-line summary, then a tight per-argument list. Every sentence conveys distinct, necessary information 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?

For a listing tool with no output schema, the description covers selection, filtering, result-size limits and truncation warning. The only gap is the absence of any hint about the fields each merge request carries, which is minor given the task is enumeration.

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 0%, so the description must carry all parameter meaning and it does: project accepts an id or full path with concrete examples, state lists the accepted values, limit documents default and max plus truncation, and target explains the config-derived server selector. This fully compensates for the empty 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 (list) and resource (merge/pull requests) scoped to a project, with the default filter (open ones) made explicit. An agent can distinguish it from list_pipelines, list_branches and other list_* siblings without opening the schema.

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

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

The default state and the enumeration of accepted state values imply when to use it (open MRs by default, widen with state), but there is no explicit when/when-not guidance or named alternative tool. Usage is inferable rather than stated.

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

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

Annotations only declare readOnlyHint=true, and the description adds real behavioral value beyond that: it explains the truncated flag, that truncation is measured via one extra fetched row, and how the agent should react. It does not cover broader runtime traits such as rate limits or auth requirements, so it is strong but not exhaustive.

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 [READ] tag and purpose, then return shape, then the truncation caution, then per-arg notes. Well organized with little waste, though the 'never guessed' phrasing is slightly redundant with the preceding sentence.

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 list tool with no output schema, the description covers return keys, the truncation edge case, and every parameter. What remains unaddressed is marginal — e.g. auth context — but nothing an agent needs 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 description coverage is 0%, so the description carries the full burden and does so: project documents the accepted 'group/project' path form, status gives example values, limit states default 20 and max 99, and target explains it comes from config and may be omitted for the default.

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 ('Recent pipelines/runs for a project') with ordering ('newest first') and a return shape, so an agent can tell it apart from pipeline_detail or pipeline_jobs. It does not, however, explicitly name a sibling or contrast itself with them, so it stops short of a 5.

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

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

Usage is only implied by the verb and by the truncation note directing the agent to re-run with a higher limit. There is no statement of when to reach for list_pipelines versus pipeline_detail or pipeline_jobs, nor prerequisites such as auth scope.

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 goes further, disclosing the return envelope ({projects, returned, limit, truncated}) and explaining that 'truncated' means the server held more rows than were returned and that this is 'measured, not guessed.' That is genuine behavioral context beyond the annotation, though it omits auth/rate-limit caveats.

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 a '[READ]' tag, then the return shape, then a compact Args block. Nearly every line earns its place, with only minor redundancy (limit default 50 restated from the 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 describing the return envelope and truncation semantics, and it fully covers all three parameters. It is sufficient to call the tool correctly; only the shape of individual project entries is left unspecified.

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 0%, so the description carries the full burden and does document all three params: search as an optional name filter, limit with default 50 and max 99, and target as a config target name omittable for the default. The max-99 bound and filter semantics are value added over the raw schema, but individual project return fields are left implicit.

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 ('Projects/repositories the token can see'), states the access scope ('the token can see'), and adds the differentiating payload ('with storage numbers'). An agent can distinguish this listing tool from project_detail 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?

Usage is only implicit – it is a list tool, so one infers 'use this to enumerate projects.' The only real guidance is 'omit [target] for the default,' which is a parameter hint rather than a when-to-use rule. No mention of when to prefer project_detail or any other sibling.

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

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

Annotations only declare readOnlyHint=true, which the '[READ]' tag merely restates. The description goes beyond that by disclosing the return shape ({project, protections, returned, limit, truncated}) and the presence of truncation, which is valuable given there is no output schema. It stops short of explaining pagination semantics, auth requirements, or what a truncated response implies for follow-up calls.

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 purpose line, then the return shape, then a tight args list — every sentence carries information with no padding. Well sized for a three-parameter read 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 low-complexity read-only list tool with no output schema, the description covers purpose, all three parameters, and the response envelope including truncation. Nothing essential for calling it correctly is missing, though paging guidance would be a bonus.

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?

With 0% schema description coverage, the description fully carries the burden: it explains project accepts an id or full path, limit is max rows with a default of 100, and target is a server target name from config that may be omitted for the default. No parameter is left ambiguous.

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: 'Branch-protection rules for a project (incl. force-push flags).' The resource and the explicit mention of force-push flags make it unmistakable from generic siblings like list_branches, and the '[READ]' prefix signals it is not the mutating update_branch_protection.

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 statement of when to use this tool versus alternatives such as list_branches or update_branch_protection, no prerequisites (e.g. required access level), and no explanation of what to do when results are truncated. Usage is only inferable from the name and '[READ]' tag.

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

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

The [READ] tag is redundant with readOnlyHint=true, but the description adds real behavioral detail the annotations do not: results are newest-first, the server caps limit at 99, and the response carries a 'truncated' flag when more rows exist. That truncation signal is exactly the kind of context an agent needs to decide whether to re-query.

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

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

One front-loaded sentence establishes the operation, and the Args block is compact and scannable with no filler. Every clause adds information an agent cannot get from the 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 three-parameter read tool with no output schema, the description covers scope, ordering, parameter semantics, and the truncation contract, which is close to everything needed. It could mention whether additional rows are reachable (offset/cursor) once truncated, but the essentials are 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?

With schema description coverage at 0%, the description carries the full burden and does so: project accepts an id or full path, limit defaults to 20 with a max of 99, and target is a server target name that can be omitted for the default. Each parameter's meaning and accepted values are defined beyond the bare types 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?

States a specific verb and resource ('Releases for a project') plus an ordering guarantee ('newest first'), so an agent immediately knows what comes back. It does not, however, differentiate itself from siblings such as list_artifacts or list_pipelines, which is the only thing keeping it 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?

Usage is implied by the resource name — an agent would infer 'use this to see a project's releases' — but there is no explicit when-to-use, when-not-to-use, or named alternative. The 'target' arg hints at multi-server context but no guidance is given on choosing it.

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

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

Annotations only declare readOnlyHint=true; the description adds substantial behavior beyond that: result ordering (offline/paused first *before* the truncation cut), the truncation flag, the returned row count, and the platform-capability error semantics. These are exactly the traits an agent needs to interpret partial results.

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 purpose and the sorting guarantee, then the platform caveat, then args — a sensible order. The Gitea paragraph is long relative to the tool's simplicity, but it earns its space by preventing a misdiagnosed retry loop.

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, yet the description sketches the return object ({runners, returned, limit, truncated}), which is the key missing structured information. Remaining gaps are the 100-vs-99 limit discrepancy and no mention of pagination or how to page past the cap.

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 0%, so the description carries the burden and largely delivers: it enumerates the status values (online, offline, paused, stale) that the schema leaves as an unconstrained string, and explains target as a config name where omission means the default. Minor flaw: it says limit is 'default 100, capped at 99', which conflicts with the schema default of 100 and is internally odd.

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 and scope: '[READ] All runners visible to the token, offline/paused first.' The 'All runners' framing implicitly separates it from runner_detail (single runner) and from pause_runner/resume_runner (mutations). An agent can route correctly without opening any schema.

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

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

Gives strong when-not guidance for the Gitea case, explicitly telling the agent not to retry or report the server unreachable and to answer from the pipeline/job surface instead. It does not, however, name the sibling tools it competes with (runner_detail, runner_health_rca) or state when a status filter is preferable to a full listing.

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?

Goes well beyond annotations: it discloses the read-before-write sequence so prior state is recorded, the exact runtime effect (no new jobs picked up, in-flight jobs finish), reversibility, and a dry_run preview path. There is mild tension with destructiveHint=true, but pause is a reversible state change rather than data destruction, so this is a conservative-annotation mismatch rather than a contradiction.

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 write/risk tag and then the single-sentence purpose; the Args block is warranted given 0% schema coverage. The dry_run preview instruction is stated twice (prose and Args), which is a small 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 no-output-schema mutation tool, it covers the essential concerns an agent needs: safety class, reversibility, side effects on running jobs, and a preview option. It does not state permission requirements or what the read-before-write record enables on the return side, but nothing critical 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 0%, so the description must carry the burden and largely does: runner is identified as an id sourced from list_runners, dry_run is explained as a preview toggle, and target is defined as a server name from config with 'omit for the default'. Only the runner id's format is left unspecified.

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 ('Pause a runner') and immediately qualifies it as reversible via undo, which cleanly separates it from resume_runner. A [WRITE][risk=medium] tag front-loads the operation class so an agent can place it among the read-heavy siblings.

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

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

Gives clear context for when this operation is appropriate ('A paused runner stops picking up new jobs; running jobs finish') and points at undo as the inverse. It does not explicitly name resume_runner or undo_apply as the alternatives, so the routing guidance is implied rather than stated.

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

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

Annotations already declare readOnlyHint=true, and the '[READ]' prefix simply echoes this. The description adds a minor behavioral note ('omit [target] for the default') but says nothing about return volume, contents, or side effects beyond what annotations cover.

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 one-line summary followed by a compact Args block; every line carries information without 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?

With no output schema and minimal annotations, the description is adequate for a read-detail tool, covering all params and id sourcing. It stops short of describing what 'full detail' contains, which would help an agent decide between this and pipeline_jobs.

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 0%, so the description must carry the burden, and it does so well for all three params: project as id or full path, pipeline id sourced from list_pipelines, and target with an explicit omit-for-default instruction. It compensates meaningfully for the empty schema 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?

States a specific verb (read) and resource ('one pipeline/run's full detail'), distinguishing it from the sibling list_pipelines. However, it does not explicitly differentiate from other pipeline-scoped reads like pipeline_jobs or job_trace_tail.

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

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

The hint '(from list_pipelines)' implies the workflow for sourcing the pipeline id. Beyond that, there is no explicit when-to-use vs. alternatives such as pipeline_jobs or job_trace_tail for deeper drill-down.

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

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

Annotations declare readOnlyHint=true and the description's '[READ]' prefix is consistent. Beyond that it discloses real behavioral context: it pulls failed jobs plus trace tails, classifies from failure_reason and trace markers, and names matched evidence rather than a black-box verdict. No auth/permission or rate-limit detail, but the evidence-based angle is genuinely informative.

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

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

Front-loaded with a one-line '[READ]' summary and the core behavior before the Args/Returns blocks. The docstring-style layout is somewhat verbose but each section earns its place given the 0% schema coverage and absent 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 documents the return shape (pipelinesEvaluated, classCounts, per-pipeline headlineClass/cause/action, per-job evidence, note), and with 0% parameter coverage it documents all five args. An agent has what it needs to both call 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 0% (titles only), so the description carries the full burden and does so: project is 'id or full path (required unless failed_pipelines given)', limit and tail_lines have units/defaults, failed_pipelines documents the injected row shape, and target explains the config lookup. This adds substantial meaning the schema lacks.

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: classifies recent failed pipelines into cause+action. It names the concrete classification taxonomy (test-failure / dependency-network / runner-timeout / oom / script-error), which distinguishes it from siblings like runner_health_rca or pipeline_detail 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?

Explicitly gives two usage modes: 'Pass failed_pipelines for pure analysis, or a project to pull live,' clarifying the injection vs live-pull choice. It does not, however, contrast against alternative RCA/detail siblings like runner_health_rca or job_trace_tail for narrower scope.

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

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

Annotations only declare readOnlyHint=true, so the description adds real value: it discloses the return shape ({project, pipeline, jobs, returned, limit, truncated}) and, importantly, the truncation semantics ('when truncated is true this pipeline had more jobs than were returned'). It does not address rate limits, auth, or pagination beyond the limit, so a 4 rather than 5.

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

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

Front-loaded one-line purpose, then a compact return-shape sentence with the truncation caveat, then an Args block. Every sentence earns its place and nothing is 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 no output schema, the description takes on return-value explanation and does it well, including the truncation flag. Parameter coverage is complete despite 0% schema descriptions. The only gap is sibling disambiguation against job_trace_tail/pipeline_detail for an agent choosing among the job-inspection tools.

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 0%, so the description must carry the load, and it does document all four parameters: project (id or full path), pipeline (run id and its origin), limit (max rows, default 100), and target (server target from config, omit for default). That is near-complete compensation for the empty schema descriptions; only format/syntax edge cases are missing.

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+scope: 'Jobs of one pipeline/run with status + failure reason.' This distinguishes it from pipeline_detail and list_pipelines by scoping to jobs of a single run, and it points at list_pipelines as the source of the pipeline id. It stops short of explicitly naming the sibling it is not, so not 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?

The description explains where inputs come from ('pipeline: Pipeline/run id (from list_pipelines)' and 'target: Server target name from config'), which is useful routing context. However, it never says when to prefer this over pipeline_detail or job_trace_tail, nor when not to use it. Usage is implied rather than stated.

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

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

readOnlyHint=true already declares the safe read profile, so the annotation carries the safety burden. The description adds useful content context (byte counts for repo/artifacts) but says nothing about permissions, rate limits, or error behavior. Adequate given the annotation coverage, but not rich.

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 read tag and core purpose, then a compact Args block. Every line earns its place; the format is clean and scannable.

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

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

For a simple single-entity read with no output schema, the description covers the resource, what it returns, and the full parameter contract. Only minor gaps remain, such as precise returned fields and error cases.

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 0%, so the description must carry the load — and it does, documenting both parameters. It gives the project format with concrete examples ('group/project' / 'owner/repo') and explains that target is a config server name that may be omitted for the default.

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 ('One project's detail') and previews the payload ('repo/artifact byte counts'). The singular 'One project's' implicitly distinguishes it from the sibling list_projects, though it never names an alternative 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?

No guidance on when to use this over list_projects or other detail tools like pipeline_detail. The '[READ]' tag mirrors the annotation rather than clarifying usage context or prerequisites.

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

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

Adds real context beyond the annotations: it discloses the read-before-write step (so the harness records the prior paused state), the reversibility mechanism (undo re-pauses), and a preview mode. There is mild tension between the description's 'reversible' framing and destructiveHint=true, but they are not strictly contradictory since reversibility does not negate a state-changing write.

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 summary sentence, then behavioral notes, then a compact Args block. Efficient, though the [WRITE] tag partially duplicates what the annotations already declare.

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 3-parameter mutation tool with annotations but no output schema, the description covers purpose, precondition, preview, undo, and all parameters. It does not say what resume returns or what happens if the runner is not paused, so it stops just short of complete.

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

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

Schema description coverage is 0%, so the description carries the burden and does so adequately: runner is sourced from list_runners, dry_run previews without resuming, and target is a server target name from config with a stated default. This meaningfully supplements the bare 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 (resume) and resource (paused runner), and immediately names its inverse operation (undo pauses it). An agent can distinguish this from the sibling pause_runner 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 clear context: use when a runner is paused, dry_run=True to preview, and notes the undo path. It does not explicitly name pause_runner as the counterpart, but the 'paused runner' precondition makes the usage window clear.

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 real context beyond the annotations: it discloses that the tool reads the pipeline first so priorState captures the pre-retry status, that a retry is a new run with no undo, and that dry_run previews the effect. This is consistent with (and enriches) destructiveHint=true, idempotentHint=false, readOnlyHint=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?

Front-loaded with [WRITE][risk=medium] and the core action, followed by tight behavioral notes and an Args block. The 'Irreversible ... no undo' line partially restates what destructiveHint already conveys, a minor redundancy rather than bloat.

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 non-idempotent mutation with no output schema, the definition covers irreversibility, preview path, and prior-state recording. It omits what the call returns and any error/precondition behavior when the pipeline is not in a failed/canceled state, which keeps it short of fully complete.

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

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

Schema description coverage is 0%, so the description carries the full burden — and it does: project (id or 'group/project' / 'owner/repo' path), pipeline (id sourced from list_pipelines), dry_run (preview semantics), and target (config server target, omit for default). Every one of the four parameters is given meaning.

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?

Names a specific verb and resource ('Retry a failed/canceled pipeline') and constrains scope to failed/canceled pipelines, which distinguishes it from siblings like cancel_pipeline or pipeline_detail without needing to open 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?

Implies the right context (failed/canceled pipelines) and gives preview guidance via dry_run=True, plus an explicit irreversibility warning. It does not, however, name alternatives such as undo_apply/undo_list for recovering state, so the when-not/alternative side is left to inference.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered; the description adds real value beyond that by disclosing the GitLab-only platform constraint and the specific failure behavior on other targets. It does not cover auth requirements, but no annotations are contradicted.

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 [READ] marker, then the platform constraint, then the Args block — a sensible priority order with no redundant filler. The Gitea-teaching-error sentence is slightly verbose but earns its place as an error-behavior disclosure.

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 usefully enumerates the returned fields and covers both parameters plus the platform limitation. Complete enough for a simple 2-param read tool; only auth/permission expectations 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 description coverage is 0%, so the description carries the load and largely does so: it explains runner ('Runner id (from list_runners)') and target ('Server target name from config; omit for the default'), including the default/omission behavior. It doesn't state the id's format, but both parameters are meaningfully documented.

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 singular resource ('One runner's full detail') and enumerates the returned fields (contacted_at, tags, paused, version). It explicitly contrasts with the sibling it could be confused with, noting the runner id comes from list_runners, so an agent can separate it from list_runners 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 context: platform restriction ('GITLAB ONLY — a Gitea target raises the same teaching error as list_runners') and the prerequisite source for the id (list_runners). It stops short of explicitly stating when to pick this over runner_health_rca, which is left to inference.

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

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

The readOnlyHint annotation already covers the safety profile, and the description adds substantial context beyond it: the exact criteria for stale (no contact for stale_contact_min minutes), paused, and saturation, plus the returned threshold block and the note field. It omits error/empty-fleet behavior and auth requirements, but the analysis semantics are unusually well disclosed.

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 READ tag and purpose, then organizes Args and Returns into labeled sections. It is longer than average but the length is earned by the zero-coverage schema, so almost every sentence carries information.

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

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

For a 6-parameter tool with no output schema, the description documents all parameters with defaults and explains the returned dict (runnersEvaluated, flaggedRunners, longQueuedJobs, saturatedTags, thresholds, note). Nothing an agent needs to select or 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?

With 0% schema description coverage, the description carries the full burden and does so well: it defines stale_contact_min, queue_sec (default 300), saturation_ratio (default 2.0), the injected row shapes for runners and queued_jobs, and target semantics. This adds real meaning (what 'stale' and 'saturated' mean) on top of bare defaults.

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 (flag) and precise resources (offline/stale/paused runners, long-queued jobs, tag saturation), and frames itself as the 'flagship capacity RCA'. An agent can distinguish this diagnostic from siblings like list_runners, runner_detail, or stale_work_audit without opening any schema.

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

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

Gives clear operating modes: 'Pass runners / queued_jobs for pure analysis, or a target to pull the fleet live.' This tells the agent how to invoke in either offline-analysis or live-pull form. It does not explicitly name alternatives such as stale_work_audit, so it stops short of full when/when-not 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 the '[READ]' tag is largely redundant. The description adds that a revision is returned alongside the version, but discloses nothing about auth needs, target resolution behavior, or failure modes. With annotations covering the safety profile, a 3 is appropriate.

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

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

One front-loaded sentence plus a compact Args block; nothing is wasted. Slightly formal structure but appropriately sized for a single-parameter read 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 simple read tool with no output schema and one optional parameter, the definition is nearly complete. It identifies what is returned (version and revision) and how the parameter behaves, though it could note the source of the target config values.

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 0%, so the description must carry the parameter burden, and it does: it explains 'target' as a server target name from config and clarifies that omitting it uses the default. This meaningfully exceeds the bare schema, which has no description at all.

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 resource (CI/CD server version and revision) with a clear read intent. It distinguishes well from siblings, which are all pipeline/runner/artifact operations, though it does not explicitly name a sibling.

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?

No guidance on when to call this versus alternatives, nor any prerequisites. The '[READ]' tag hints at intent but provides no usage context, and there are no exclusions or conditions stated.

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

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

Annotations only declare readOnlyHint=true, and the description reinforces this with the [READ] tag plus valuable detail the annotation lacks: the specific flag conditions (idle past stale_mr_days, unprotected default branch, force-push allowed), that every flag carries its numbers, and the returned dict shape. It stops short of describing failure modes or live-pull authentication needs.

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 flagship framing and flag list, then a tight Args block. Some redundancy with the schema defaults, but every line carries semantic value and the structure is easy to scan.

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 supplies the return dict keys ({staleMergeRequests, staleBranches, protectionGaps, counts, thresholds, note}), covers both input modes, and defines the flagging thresholds. An agent has everything needed to call and interpret it.

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 0%, so the description carries the full burden and does: it documents all 8 params with defaults (stale_mr_days=14, stale_branch_days=90), the required-unless-injected rule for project, row field shapes for each injected array, and the target meaning. This far exceeds what the bare schema conveys.

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 ('stale work audit') and enumerates exactly what it flags: long-open MRs/PRs, inactive branches, protection config gaps. This clearly distinguishes it from sibling list tools like list_merge_requests or list_branches, which merely enumerate raw resources.

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 operating modes ('Pass injected rows for pure analysis, or a project to pull live') so the agent knows how to invoke it. It doesn't explicitly name sibling alternatives or exclusions, but the context for use is unambiguous.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true and idempotentHint=false; the description adds real value on top by explaining that the actual risk tier lives with the dispatched inverse tool, that dry_run previews without executing, and that the token is single-use. It does not describe what the inverse dispatch returns or what failure looks like, so it is not maximally transparent.

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 [WRITE][risk=medium] tag and the core behavior/constraint sentences are front-loaded and efficient, and the Args block is compact. The Args list partially restates schema parameter names, but each entry adds meaning, so waste is minimal.

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 non-idempotent, destructive, three-parameter mutation with no output schema, the description supplies the missing context an agent needs: the risk marker, the once-only token rule, the preview path, and parameter sourcing. Only the result shape of the dispatched inverse call is left unspecified, which 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 0%, so the description carries the full burden and largely meets it: undo_id is traced to its source (undo_list or `_undo_id` in a write result), dry_run is defined as a preview flag, and target is explained as pass-through to the inverse tool. The pass-through semantics of `target` (when it is rejected or ignored) remain somewhat vague.

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 ('Apply a recorded undo') and explains the mechanism (dispatching its inverse tool), which separates it cleanly from the sibling undo_list that only lists tokens. An agent can immediately tell what this does that its siblings do not.

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 the context of use (apply a token obtained from undo_list or an `_undo_id` in a write result) and offers dry_run=True as the preview path, plus the constraint that a token can be applied only once. There is no explicit when-not-to-use or named alternative beyond undo_list, so it stops just 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?

Beyond the readOnlyHint annotation it discloses non-obvious behaviors: the one-extra-row truncation measurement, the meaning of effectVerified=false (probable vs confirmed changes), and that target is accepted only for CLI uniformity. These are exactly the kind of traits an agent cannot infer from 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?

Front-loaded with purpose, then return shape, then the critical effectVerified caveat, then args. Well organized, though the effectVerified paragraph is somewhat long and slightly repetitive in emphasizing the probable-not-confirmed distinction.

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 present, the description supplies the return shape ({undos, returned, limit, truncated}), the row semantics, and the safety caveat for applying entries. Nothing essential for correct invocation 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 0%, yet the args section documents limit (default 50, max 500) and explicitly marks target as unused. The description fully compensates for the undocumented 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?

Starts with a specific verb and resource: 'List recorded, not-yet-applied undo tokens (most recent first)'. It clearly distinguishes itself from the sibling undo_apply by framing the tokens as the input to that tool rather than the action itself.

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 tells the agent the follow-up workflow: 'Use the undoId with undo_apply', and the effectVerified note prescribes checking live state before applying. It lacks an explicit 'when not to use' but the context for invocation is clear.

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 (readOnlyHint=false, destructiveHint=true, idempotentHint=false), the description discloses the read-before-write pattern, that an undo record is captured, that the undo replays this same tool with prior settings, and that dry_run offers a preview. This is unusually rich behavioral context.

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 leading tag line is dense and front-loaded, and the Args block is well organized. The undo/read-first explanation is slightly verbose but each sentence adds real value, so waste is minimal.

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 mutation tool with no output schema, the description covers the mechanics (read-first, undo, dry-run) and every parameter. Only minor gaps remain, such as whether a success response or returned undo handle needs to be inspected.

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 0%, so the description must carry the full burden — and it does, documenting all six parameters in prose: project (id or full path), branch (from list_branches), protect, allow_force_push (safe default), dry_run, and target (config target name). It fully compensates for the schema gap.

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

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

The description opens with a specific verb and resource: 'Protect/unprotect a branch'. It also explicitly distinguishes the operation's nature via '[WRITE][risk=medium]' and 'reversible', letting an agent separate it from read-only siblings like list_protected_branches or list_branches.

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 clear condition for previewing ('Pass dry_run=True to preview') and notes the safe default for allow_force_push, but it never states when to choose this tool over alternatives (e.g., when to use list_protected_branches first) or explicit when-not-to-use guidance.

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