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

Annotations already declare readOnlyHint=true, so the safety bar is lower; the description adds genuinely useful context beyond that: nearfull is 85% of total, no clock is read, and the projection is pure arithmetic, plus the 'insufficient-data' fallback state. It does not discuss pagination or response shape, but those are minor here.

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] marker and the core purpose, followed by the arithmetic caveat and an Args section. No sentence is wasted, though the Args block partly mirrors parameter names already visible in 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 does explain the key return concepts (daysToNearfull, 'insufficient-data') and the nearfull threshold. It is complete enough to call correctly, though it could say more about the usage payload returned by default.

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: both daily_growth_bytes ('observed daily growth in bytes; omit for a usage-only view') and target ('Ceph target name from config; omit for the default') get meaning and default behavior 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?

The description opens with a specific verb+resource: '[READ] Capacity usage + a deterministic days-to-nearfull projection.' No sibling tool (osd_df, pool_df, cluster_status) does capacity forecasting, so an agent can identify this tool's distinct role immediately.

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 clear conditional context: passing daily_growth_bytes yields daysToNearfull, omitting it yields 'insufficient-data' and a usage-only view. It does not name competing siblings or exclusions, which keeps it at 4 rather than 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?

readOnlyHint=true already establishes the safety profile, and the description adds real context beyond it: the returned rank states, client/standby counts, and the diagnostic significance of the trimming flag. It stops short of describing permissions or output formatting, but for a read-only diagnostic that is a minor omission.

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] marker and the core resource, then the returned fields, then the arg. The 'notorious'/'quietly precedes metadata stalls' phrasing is flavor, but it earns its place by explaining why the trimming signal matters.

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 does so by naming the fields surfaced. Purpose, returned content, and the single parameter are all covered; only secondary details like scope across multiple filesystems or failure modes are absent.

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

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

Schema coverage is 0% and there is one parameter, yet the description compensates by explaining that target is a 'Ceph target name from config' and that omitting it selects the default. That fully covers the parameter's meaning and default behavior, so no gap remains.

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 — per-filesystem MDS ranks — and enumerates exactly what it surfaces (rank state, client/standby counts, the behind-on-trimming flag). No sibling tool covers CephFS metadata; mon_status/mgr_status/osd_tree are clearly different subsystems, so the agent can select this 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?

Usage is only implied: the note that the trimming flag 'quietly precedes metadata stalls' hints at using this for early CephFS metadata-degradation detection, but there is no explicit when-to-use, when-not-to-use, or named alternative. Adequate but leaves routing to inference.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true and non-idempotent, so the write profile is covered. The description adds genuinely new behavioral context: the operation is reversible because it records an undo that toggles the flag back, pointing to the undo_list/undo_apply siblings. It doesn't note permission requirements or blast radius, so not a 5.

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

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

Front-loaded with the [WRITE][risk=medium] tag, then purpose, usage, and an Args block — logical and easy to parse. The Args block largely restates parameter names already visible in the schema, so a little space is not fully earned.

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 3 params, one required, no output schema, and annotations covering the safety profile, the description supplies what an agent needs: what the flag does, when to use it, and reversibility. Missing only edge details such as valid flag enumeration and target resolution.

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 mostly delivers: flag examples, enable=True/False semantics (set vs clear), and target as a Ceph target omitted for the default. The flag list is truncated with an ellipsis and target's valid values are left vague ('from config'), so coverage is good but not exhaustive.

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 (set/unset a cluster flag) and immediately enumerates concrete flag values (noout/nobackfill/norecover/noscrub). No sibling tool manipulates cluster flags, so an agent can distinguish this instantly from the status/list 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 a clear usage context — 'heavily used before maintenance (e.g. set noout while rebooting a host)' — which tells the agent when this tool is appropriate. It stops short of naming alternatives or stating when NOT to use it (e.g. vs osd_mark_out or a config change), 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?

The readOnlyHint annotation already establishes the safety profile, and the description reinforces it with a [READ] tag rather than contradicting it. It adds genuine behavioral context beyond the annotation by describing the response shape (per-check cause plus suggested action), though it says nothing about permissions, result size, or failure modes.

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?

Tightly front-loaded: the operation and the call-first guidance come before the argument note, and every clause adds new information (decoding behavior, example codes, default target). 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 single-optional-parameter read tool with no output schema, the description supplies everything needed: what it reads, when to call it, what the return contains, and how the one argument behaves. Annotations cover safety, so nothing material is missing.

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

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

Schema description coverage is 0% and there is one parameter, so the description carries the burden: it explains that 'target' is a Ceph target name from config and that omitting it uses the default. That fully covers the single parameter's meaning and default value, though it does not say how to discover valid target names.

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

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

States a specific verb and resource (read HEALTH status) plus a distinctive value-add: it decodes raw HEALTH_WARN/ERR check codes like PG_DEGRADED and OSD_NEARFULL into a plain-language cause and suggested action. That decoding behavior separates it from generic siblings such as cluster_status, mon_status, and osd_tree, so an agent can pick it 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 an explicit trigger: 'Call this first on any "the cluster is unhealthy" question.' This is a clear entry-point instruction, but it names no alternatives and gives no when-not guidance (e.g., when to prefer mon_status or osd_tree for deeper diagnosis), which keeps it below the top band.

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 covers the safety profile, and the description usefully adds the summary's contents and the 'compact' scope. It does not mention return format, latency, or failure behavior, so it clears the lower annotated bar but adds only moderate 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?

Two compact lines with the summary purpose front-loaded ahead of the args block. Every clause earns its place, and the '[READ]' tag is a useful leading signal.

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 one-optional-param read tool with no output schema, the description covers purpose, output contents, and parameter defaulting. Only the absence of guidance on when to prefer this over sibling status tools keeps it from being 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 parameter burden and does so well: it explains that 'target' is a Ceph target name sourced from config and that omitting it uses the default. This meaningfully exceeds the bare 'Target' schema title.

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: a compact 'ceph -s' summary with an explicit content list (mons, OSDs up/in, PGs, usage, objects). This implicitly distinguishes it from detail-oriented siblings like mon_status, osd_tree, or cluster_health, but it never names an alternative to route between 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?

The '[READ]' tag signals a non-mutating status check, and the args note explains the default target. However, there is no explicit when-to-use guidance or contrast with cluster_health, pg_summary, or the other status tools, leaving selection 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 establishes the safety profile, and the '[READ]' tag merely restates it. What the description does add is the scope of the response (standbys and enabled modules), which is useful since there is no output schema, but it omits any caveats about permissions or target resolution failures.

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

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

Two tight lines: the '[READ]' scope sentence is front-loaded and the Args block carries only the one parameter. No filler, though the Args-style formatting is slightly verbose for a single optional argument.

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 one optional parameter, no output schema, and a read-only annotation, the description supplies enough: it names the reported content and explains the single argument. An agent could invoke it correctly, missing only edge cases such as invalid target handling.

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: 'target: Ceph target name from config; omit for the default' explains both meaning and the null/default behavior. Only the format or source of valid target names 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 resource (mgr) and enumerates exactly what it reports: the active mgr, its standbys, and enabled mgr modules. It is clearly distinguishable from sibling status tools like mon_status or osd_tree by resource, 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 when-to-use guidance, no exclusions, and no routing to sibling tools. The only usage hint is the parameter note 'omit for the default,' which tells the agent how to call it but not when to prefer it over mon_status or cluster_status.

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

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

readOnlyHint=true already tells the agent this is a safe read. The description reinforces that with a [READ] tag and adds useful trigger context, but discloses nothing further about behavior (e.g., what happens on an unreachable mon, or whether the output changes with quorum state). Adequate but adds limited value 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?

Tightly structured: purpose first, then a clear routing condition, then the single argument. Every sentence earns its place with no redundancy.

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

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

For a read-only status tool with no output schema, the description adequately sketches the return content (quorum membership and monmap epoch) and covers the sole parameter. Nothing critical is missing, though output format details are absent.

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

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

Schema description coverage is 0%, so the description carries the burden and does add real meaning: 'target' is a Ceph target name from config, and omitting it uses the default. That resolves the only ambiguity an agent would have, though it gives no format examples.

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 resource (monitor quorum) and states exactly what is returned: mons in/out of quorum plus the monmap epoch. This is clearly distinguishable from siblings like mgr_status, osd_tree, and cluster_health, which cover different subsystems.

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 an explicit trigger — health flags MON_DOWN or a clock-skew warn — which is exactly the situation where an agent would reach for this tool. It does not name a when-not condition or an alternative tool, so it stops short of a 5.

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

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

The readOnlyHint annotation already establishes the safe read-only nature, so the '[READ]' label is redundant. The description adds useful behavioral context about ordering (most-full first) and flags, but does not explain what the flags mean, pagination, or 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?

The description is short, front-loaded, and contains no filler. The purpose is stated first, followed by the only parameter's semantics, making it easy for an agent to parse quickly.

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

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

For a low-complexity, single-parameter, read-only tool with no output schema, the description provides enough context to call it correctly and understand the general return shape. It could be improved by clarifying the output flags, but the core 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?

With only one parameter and 0% schema description coverage, the description compensates well by explaining that target is a 'Ceph target name from config' and that omitting it uses the default. This adds meaningful semantics beyond the bare anyOf string/null 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 states a specific read operation: per-OSD utilisation with most-full-first ordering and near/backfill-full flags. It clearly identifies the resource and metric, though it does not explicitly distinguish this from sibling tools such as osd_tree or osd_perf.

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 guidance on when to use this tool versus alternatives like osd_tree or osd_perf. The '[READ]' tag and optional target hint at a safe read operation, but usage context and exclusions are absent.

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, idempotentHint=false and destructiveHint=true, so the safety profile is covered. The description adds value the annotations don't: a 'risk=medium' grading and the operational meaning of the mutation. It still omits what actually happens to data/PGs (backfill/recovery) and whether the change is reversible via osd_mark_out.

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?

Very tight: a bracketed marker for operation type and risk, then a one-line semantic gloss, then a compact two-entry Args block. Front-loaded with the operation and risk, and nothing is wasted.

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

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

For a 2-param write tool with annotations covering the safety profile and no output schema, the definition supplies what an agent needs: the write/risk marker, the semantic meaning, and documentation of both parameters. It could go further on side effects (recovery/backfill triggered, reversibility), which is the only meaningful remaining gap.

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

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

Schema description coverage is 0%, so the description must carry the burden — and it does document both params, noting osd_id is a numeric id sourced from osd_tree and that target can be omitted for the default. It adds the provenance of the id, which the bare schema does not. Minor gap: no format hints for target.

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 (mark an OSD 'in') and immediately glosses the semantics: 'return a drained/repaired OSD to service'. This makes the direction of the operation unambiguous. It does not explicitly name the sibling osd_mark_out, so it stops short of full sibling differentiation.

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 '(return a drained/repaired OSD to service)' implies the appropriate context — you use this after a drain or repair — which is real usage guidance. However there is no explicit when-to-use vs osd_mark_out/osd_reweight routing, and no stated prerequisites or exclusions.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is set; the description goes further by naming the concrete risks (recovery storm, min_size breach) and the dry_run escape hatch. It does not state whether the action is reversible or whether it requires cluster-health preconditions.

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 tag and consequence before the args block; every line adds information. Minor redundancy in restating param names, though that restatement is justified given zero schema coverage.

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 mutation with no output schema, the description covers the operation, its risk, the preview path, and every parameter. An agent has everything needed to decide and invoke 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 description coverage is 0%, so the description carries the full burden — and it does, documenting all three params: osd_id as a numeric id sourced from osd_tree, dry_run as a preview switch, and target as a Ceph config name that can be omitted. 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+resource ('Mark an OSD out') and immediately names the consequence ('drains its data'), which separates it cleanly from siblings like osd_mark_in, osd_reweight, and osd_purge. The [WRITE][risk=high] tag further classifies it upfront.

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 to invoke (draining an OSD) and points to osd_tree as the source of osd_id, plus recommends dry_run=True to preview. It stops short of naming the inverse tool (osd_mark_in) or the operational precondition (cluster must tolerate the reduced redundancy).

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]' marker and 'slowest first' ordering disclose real behavior beyond the readOnlyHint annotation, which is useful. However, nothing is said about what the output contains beyond latency metrics, whether results are truncated, or any scope 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 short, front-loaded elements: a one-line purpose followed by the arg note. No filler, though the 'Args:' block formatting is slightly heavier than needed for a single optional parameter.

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-parameter read-only diagnostic with no output schema, the description gives purpose, ordering, and parameter default semantics — enough to call it correctly. Only the returned fields are left unspecified, which is a minor gap given no output schema exists to cover them.

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 burden and does so: it explains that target is a Ceph target name sourced from config and that omitting it selects the default. This is meaningful semantic content the bare 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 resource and metric: per-OSD commit/apply latency, ordered slowest-first, with the intent 'find the slow disk'. It is distinguishable from the broadly-named sibling slow_ops, though it never names that sibling directly for contrast.

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

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

The phrase 'find the slow disk' implies a diagnostic use case, which is more than nothing, but there is no explicit when-to-use vs. when-not guidance and no alternative tool referenced (e.g., slow_ops for cluster-wide slow op 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?

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds material context: the operation is explicitly "Irreversible," it names the exact underlying steps (destroy + crush rm + auth del), and it documents the dry_run escape hatch. This exceeds the annotation bar with concrete destructive-behavior 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 a [WRITE][risk=high] tag, then the core action, then the safety prerequisite, then a clean Args block. Every sentence earns its place with no redundancy.

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

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

For a high-risk destructive tool with no output schema, the description covers action, irreversibility, prerequisites, and parameter semantics well. The only minor gap is that it doesn't describe failure/partial-failure behavior across the three sub-operations (destroy/crush/auth), which would matter for a multi-step purge.

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 it does: osd_id ("Numeric OSD id (from osd_tree)"), dry_run ("preview without purging"), and target ("Ceph target name from config; omit for the default"). All three parameters gain meaning absent from 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+resource ("Purge an OSD") and immediately unpacks what purging means ("destroy + crush rm + auth del"), which is far more specific than the tool name alone. It is easily distinguishable from the many read-only siblings (osd_tree, osd_df) and the milder mutation siblings (osd_mark_out, osd_reweight).

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 an explicit prerequisite sequence: "Drain first (osd_reweight 0 → mark out → wait active+clean) before purging," naming the sibling tools involved. It also points to the safe alternative ("Pass dry_run=True to preview"), so both when-to-use and how-to-de-risk are covered.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the safety profile is covered. The description adds real value beyond that: an explicit [WRITE][risk=medium] tag, the reversibility guarantee (returns to prior weight), the 0.0 = full-drain semantics, and the dry-run preview behavior. It omits permission/authorization requirements, which keeps it from a 5.

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

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

Front-loaded with the operation type, risk level, and effect, followed by a single dry-run line and a compact Args block. Efficient overall, though dry_run's behavior is stated twice (inline sentence and Args), a minor redundancy.

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

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

With no output schema and no annotation detail on returns, the description still covers the essentials an agent needs: mutation classification, reversibility, dry-run path, and full parameter semantics. Return payload shape is left unspecified, 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 0%, so the description carries the full burden, and it documents every parameter: osd_id with its source (osd_tree), weight with its valid range 0.0–1.0 and drain meaning, dry_run's read-only preview behavior, and target with its config origin and default omission.

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 ("Set an OSD's reweight") and immediately clarifies the semantic effect ("0.0 drains it"). An agent can distinguish this from the adjacent osd_mark_out/osd_mark_in siblings because reweight is gradational while those are binary in/out operations.

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 operational guidance: pass dry_run=True to preview current→target weight before applying, and that the change is reversible to the prior weight. It doesn't explicitly name when to prefer this over osd_mark_out, but the dry-run and reversibility cues establish clear usage context.

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

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

The readOnlyHint annotation already establishes that this is a non-mutating read, and the '[READ]' prefix merely restates that. The description does add value by naming the fields the agent will get back, but says nothing about result size, pagination, or failure behavior for an unreachable target. Adequate 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?

Two compact lines with the payload description front-loaded before the argument note. Slightly mechanical 'Args:' formatting and the redundant '[READ]' tag cost it a point, but 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?

For a single-optional-parameter read tool with no output schema, the definition covers what the tool is, what it returns, and how to handle the only argument. Only the absence of guidance relative to sibling OSD tools keeps it from being 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% (the schema only has a bare 'Target' title), so the description must carry the parameter explanation — and it does, defining target as a Ceph target name from config and explaining that omission selects the default. This meaningfully 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 gives a concrete verb+resource ('All OSDs') and enumerates the data returned (up/in state, weight, host, device class), which is specific enough for an agent to know this is the OSD topology listing. It does not explicitly distinguish itself from close siblings like osd_df or osd_perf, 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?

There is no guidance on when to choose this over osd_df, osd_perf, or cluster_status, and no stated preconditions. The only usage hint is 'omit for the default' for the target argument, which is parameter-level rather than tool-level 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 only give readOnlyHint=true, and the '[READ]' tag plus the explicit return envelope and truncation semantics add real value beyond that. It explains what 'truncated: true' implies, which is behavioral detail the annotations cannot carry. It does not cover cost, sorting, or refresh characteristics, so not a 5.

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

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

Front-loaded with the operation and usage trigger, then the return shape, then Args — the important routing information appears first. The Args block repeats the schema default of 200, a minor redundancy, but nothing else is wasted.

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

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

With no output schema, the description compensates by declaring the return object keys and truncation flag. For a two-parameter read tool with readOnlyHint set, an agent has everything needed to call and interpret it; only sibling differentiation and pagination/ordering detail are absent.

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

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

Schema description coverage is 0%, so the description carries the burden, and it does document both parameters: target as 'Ceph target name from config; omit for the default' and limit as max stuck-PG rows with default 200. That meaningfully exceeds the bare schema, though 'limit' simply restates the schema 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 resource (stuck PGs) with a parenthetical enumeration of the states counted as stuck (inactive/unclean/stale/undersized/degraded) and the payload returned (implicated OSDs). It does not name or distinguish itself from the nearby pg_summary sibling, so it stops short of a full 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?

Gives a concrete trigger: 'Use this when a PG is not recovering — it surfaces the OSD ids to investigate.' That is clear operational context, though it names no alternative (e.g. pg_summary) and states no when-not-to-use condition.

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 readOnlyHint annotation to disclose the truncation contract: unhealthyCount is the true total while the unhealthy list is capped at limit and flagged truncated:true, with explicit advice to re-run at a higher limit. This is exactly the non-obvious behavior an agent needs to avoid misreading a partial result as complete.

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 the one-line purpose, then adds guidance in descending order of importance. The truncation warning and Args block are justified, though the description runs longer than strictly required for a two-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-only tool with no output schema and two params, the description covers what is returned, the truncation edge case, and both arguments. 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 coverage is 0%, so the description must carry the params, and it does: target (Ceph target name from config, omit for default) and limit (max unhealthy rows, default 200). Both are explained beyond their bare names, though target's expected format is only loosely characterized.

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 with precise scope: a PG state histogram plus every PG not active+clean. It is clear enough that an agent understands exactly what comes back, but it never differentiates itself from the closest sibling (pg_dump_stuck), which an agent could plausibly reach for on the same question.

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

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

Gives concrete usage context for when to invoke ('are my PGs healthy?') and what it answers. It stops short of naming exclusions or pointing to pg_dump_stuck for the stuck-PG case, so it is clear context without alternatives.

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, idempotentHint=false, and destructiveHint=true, so the '[WRITE]' tag is largely redundant. The description does add the 'risk=medium' severity rating and implicitly confirms the non-idempotent create semantics, but it says nothing about failure behavior when the pool already exists, cluster-side side effects, or whether the call blocks.

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 signal, then a tight per-argument list. The defaults (32, 3, "rbd") duplicate what the schema already declares, which is minor waste, but the rest of the text earns its place.

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

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

For a five-parameter mutation tool with no output schema, the description covers what is being created and all inputs, and annotations carry the destructive/non-idempotent profile. It stops short of stating prerequisites (cluster reachability, auth level) or what happens on a name collision, which an agent provisioning into an existing cluster would want.

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: every one of the five parameters is explained, including the enum values for 'application' ("rbd", "cephfs", "rgw") that are absent from the schema, plus the meaning of 'target' as a config-sourced Ceph target name.

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 — 'Create a replicated pool' — which an agent can immediately distinguish from pool_delete, pool_ls, and pool_df. The '[WRITE][risk=medium]' prefix reinforces the operation type up front.

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 guidance on when to use this tool versus alternatives such as rbd_image_create (which may implicitly create a pool) or the pool_* mutation siblings like set_pool_size. No prerequisites, permissions, or environment conditions are mentioned; the agent must infer that this is the initial pool-provisioning step.

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 destructiveHint=true and readOnlyHint=false, but the description adds substantial context beyond them: the deletion is irreversible, the refusal set (.mgr, .rgw.root, mgr-owned pools) and why — deleting the mgr pool severs the REST transport the tool itself uses — and that these guards hold even under dry_run. That is exactly the kind of behavioral disclosure 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-loaded with the write/risk tag and the core consequence, then the preview path, then the refusals, then the Args block — a sound ordering. Minor redundancy: 'Irreversible' and 'no undo once the data is gone' restate the same fact, and the refusals are already stated in the header text.

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

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

For a high-risk mutation with no output schema and three undocumented-by-schema parameters, the description supplies the consequences, the preview workflow, the refusal conditions, and the target semantics. An agent has everything needed to call this safely.

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: pool_name is documented with its provenance (from pool_ls), dry_run with its effect (preview without deleting), and target as the Ceph target name from config that can be omitted for the default. All three parameters are meaningfully explained beyond their bare names.

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

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

Opens with an explicit verb and resource ('Delete a pool') plus a scope statement that distinguishes it from siblings like pool_create or osd_purge. The [WRITE][risk=high] tag and 'destroys all of its data' immediately identify it as the destructive pool-level operation.

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?

Tells the agent to preview with dry_run=True and points at pool_ls as the source of the pool_name, which is concrete usage context. It also implies undefined undo paths ('there is no undo'), but never names undo_list/undo_apply as the alternatives, so the routing guidance stops short of explicit when-not/alternatives.

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), but the description goes further by disclosing the return shape ({"pools", "returned", "error"}) with no output schema present, and by warning that a non-null error is a failed query rather than an empty cluster. That interpretation caveat is exactly the kind of context an agent cannot get from structured fields. Auth requirements and result limits implied by "returned" are not explained.

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 the payload summary, then the return contract, then the caveat, then the arg. Every sentence carries information; 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 single-param read tool with no output schema, the description supplies the return shape, the error semantics, and the parameter meaning, which is close to sufficient. The one loose end is that "returned": N implies a cap or truncation that is never explained.

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% – the property is only titled "Target" with a null default – so the description must compensate, and it does: it explains target is a Ceph target name from config and that omitting it selects the default. That is a meaningful addition over the schema, though it doesn't say where the name comes from or how to discover valid values.

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 and the exact data returned (used/avail bytes, percent, objects, usable capacity), so an agent can tell this is a capacity/usage report rather than a listing. It never names sibling pool_ls or capacity_forecast, so differentiation must be inferred from the field list.

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 purpose (reach for this when you need per-pool capacity numbers), but there is no explicit when-to-use statement, no exclusion, and no routing to pool_ls or capacity_forecast. The only guidance given is on the parameter default.

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

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

readOnlyHint=true already tells the agent this is a safe read, so the '[READ]' prefix is largely redundant. The description does add value by naming the exact fields that come back and clarifying that omitting target falls back to the config default, but it says nothing about scope limits, clustering, or volume of 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?

The returned-field list is front-loaded and the argument note is short; every line earns its place. Slightly terse overall, but no padding to trim.

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 explains the only argument, so an agent has what it needs to call the tool. Missing only cross-references to sibling pool tools and any note on output size or filtering.

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% for the single target parameter, so the description must carry the meaning — and it does, explaining that target is a Ceph target name from config and that omitting it uses the default. That fully compensates for the undocumented schema field.

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 all pools) and enumerates the attributes returned (size/min_size, pg_num, autoscale mode, application, quota), which is more specific than a bare 'list pools'. It does not explicitly differentiate from the nearby pool_df sibling, which also reports on pools, 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?

The '[READ]' tag implies a safe inspection operation, but there is no explicit statement of when to use this over pool_df, pool_create, or the set_pool_* siblings, and no prerequisites or exclusions. Usage is only implicit.

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, idempotentHint=false, and destructiveHint=true, so the write/non-idempotent nature is covered. The description adds the risk=medium tag but omits behaviorally important facts for a create operation: name-collision handling, required auth, and size constraints.

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 risk/write tag is front-loaded and the Args block is tight with no filler. Slightly more verbosity than strictly necessary, but every line maps to a distinct parameter or constraint.

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 0% schema coverage, the description should say more about outcomes for a mutating create (e.g., what a successful call returns, or failure on duplicate names). It covers inputs adequately but leaves the result contract implicit.

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 parameters, and it does document all four: pool_name (sourced from a pool listing), name, size_bytes, and target ("Ceph target name from config; omit for the default"). The only shortfall is that size_bytes gets no unit/format detail beyond its name.

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 opening sentence gives a specific verb and resource ("Create a new RBD image in a pool") and the [WRITE][risk=medium] tag immediately signals the operation class. It is cleanly distinguishable from siblings such as rbd_image_delete, rbd_snapshot_create, and pool_create.

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

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

Usage is implied rather than stated: the note "from a pool listing" hints that pool_ls should be consulted first, and the [WRITE] tag implies a mutating context. However, it never says when to prefer this over rbd_snapshot_create, what permissions are needed, or what happens if the image already exists.

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 destructiveHint=true and readOnlyHint=false, but the description adds genuinely new context: irreversibility, that ALL data is destroyed, and a safe preview path via dry_run. It doesn't state permission/auth requirements or success/failure behavior, keeping it below 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?

Risk tags and the critical irreversibility warning are front-loaded, followed by a clean Args block. No redundant or filler 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?

For a destructive tool with no output schema, the definition covers purpose, risk, preview mechanics, and every parameter. Minor gaps remain around permissions and post-delete return behavior, but the annotations already carry the safety profile.

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 documents all four parameters: pool_name, image_name (with its source rbd_ls), dry_run, and target (including the omit-for-default rule). Descriptions are meaningful though terse for pool_name/image_name, so not quite 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 specific verb (delete) and resource (RBD image) with explicit scope ('and ALL its data'), which cleanly distinguishes it from siblings like rbd_snapshot_delete and pool_delete.

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 guidance ('Pass dry_run=True to preview') and routes discovery to the sibling rbd_ls via 'image_name (from rbd_ls)'. It lacks an explicit comparison to rbd_snapshot_delete for the snapshot-vs-image distinction, so it stops short of a 5.

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

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

The readOnlyHint=true annotation already establishes this as a safe read, and the '[READ]' tag is consistent with it. The description adds the returned field set but says nothing about permissions, pagination, or behavior on a nonexistent pool/target, so it adds only modest context 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 summary sentence followed by a tight Args block; every line is load-bearing and there is no redundancy.

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

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

There is no output schema, so the description correctly compensates by naming the returned fields, and both parameters are explained despite zero schema coverage. It is nearly complete for a read-only list tool, missing only edge-case 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 description coverage is 0% – the properties carry only a 'title' – so the description carries the full burden, and it does document both parameters, including the meaning of omission for each. It stops short of giving format examples (e.g., a target name syntax) or default behavior details.

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 ('RBD images') and even enumerates the fields returned (size, features, snapshot count), which cleanly separates it from the write-oriented siblings rbd_image_create, rbd_image_delete, and the snapshot tools. An agent can identify it without opening the schema.

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

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

The description explains the scoping behavior of both parameters ('omit for all pools', 'omit for the default'), which implies when to pass them, but it names no alternatives or when-not-to-use conditions. 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?

Annotations already declare readOnlyHint=false, destructiveHint=true, idempotentHint=false, so the safety profile is covered. The description adds meaningful context beyond that: a medium risk rating and, importantly, that the operation is reversible via snapshot deletion, which tells the agent the rollback path. Return behavior is still undisclosed.

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 operation and risk tag in one sentence, then a compact Args block where each line earns its place. No filler, though the risk/reversibility note could be merged into a slightly tighter form.

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 should ideally hint at what is returned, and it does not. Otherwise it is complete for a mutation tool: all params documented, undo path stated, and safety profile covered by annotations, leaving only return-value detail 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 param burden and largely does so: it explains pool_name, image_name (with a discovery hint to rbd_ls), snap_name, and that target should be omitted for the default. That maps to all 4 params including the optional nullable one, though format/syntax details are thin.

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 ("Snapshot an RBD image") with a write/risk tag, and the name itself distinguishes it from rbd_image_create and rbd_snapshot_delete. It does not explicitly name or contrast those siblings, so a 4 rather than 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 through the arg notes: image_name is sourced "from rbd_ls" and the reversibility line points to rbd_snapshot_delete as the undo path. However, there is no explicit statement of when to snapshot versus alternatives or any precondition (e.g., image must be quiesced/exported), so guidance is only partial.

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 destructiveHint=true and readOnlyHint=false, so the safety profile is known. The description adds value annotations cannot express: 'Irreversible' as a hard consequence plus a dry_run preview escape hatch, which is exactly the operational context an agent needs before executing.

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 severity tag, action, and irreversibility first, then the dry_run escape hatch, then the Args list. No filler sentences; every line adds 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?

No output schema exists but none is needed for a delete, and the 'irreversible' consequence plus preview path cover the critical decision factors. Remaining minor gap is the absence of any error/failure behavior or permission requirements for a high-risk mutation.

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 full burden and it does document all five parameters (pool_name, image_name, snap_name, dry_run, target), including the 'omit for the default' behavior of target. Descriptions are terse but sufficient to disambiguate each argument.

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 ('Delete an RBD image snapshot') plus a severity tag '[WRITE][risk=high]', making it trivially distinguishable from rbd_snapshot_create, rbd_image_delete, and the read-only siblings. An agent can identify scope 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?

'Pass dry_run=True to preview' gives an actionable operating instruction, but there is no guidance on when to choose this tool versus alternatives such as rbd_image_delete or undo_apply, nor any stated prerequisites/permissions. Usage is implied rather than framed.

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 description adds real value on top: it explains what it detects (LARGE_OMAP/unsharded bucket index) and that it degrades gracefully ('Partial-safe if the bucket call fails'). No annotation contradiction. Return format is not described but that is minor for a read-only diagnostic.

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 the core purpose, followed by useful signal detail and an Args block. Slightly prose-heavy ('foot-gun') but every sentence contributes; nothing is wasted.

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

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

For a single-parameter, read-only diagnostic with no output schema, the description covers purpose, the key signal it surfaces, graceful failure behavior, and the parameter. Adequate, though it could specify the return shape since no output schema exists.

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% and there is 1 parameter, so the description must carry the load — and it does, explaining that 'target' is a Ceph target name from config and that omitting it uses the default. That is the essential semantic for the only parameter.

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: it reports RGW daemons and performs a large-omap scan, flagging unsharded/oversized bucket indexes. This clearly distinguishes it from sibling *status tools (mon_status, mgr_status, cephfs_status) which cover other daemons.

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 implies diagnostic use by calling the LARGE_OMAP signal 'the top RGW performance foot-gun' and notes it is 'Partial-safe if the bucket call fails', which gives context. However, it never states when to choose this over sibling status tools or any prerequisites/exclusions, leaving usage largely inferred.

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 safety, so the bar is lower. The description adds useful implementation detail (decoding PG_NOT(_DEEP)_SCRUBBED) and clarifies it reports overdue PGs, but says nothing about output shape or scope of the 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?

Extremely tight: a one-line purpose plus a two-line args block. Front-loaded with the [READ] tag and the core purpose; no wasted words.

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?

Covers purpose and the single parameter, which is adequate for a simple read tool. But with no output schema and no annotations beyond readOnly, more could be said about what 'overdue' means or the response structure.

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 param semantics. It does explain target as a Ceph target name and that omission yields the default, which compensates meaningfully, though it doesn't clarify format or valid values.

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: identifies PGs overdue for shallow/deep scrub, and parenthetically discloses the underlying implementation (decoding PG_NOT(_DEEP)_SCRUBBED). Clear what it returns, though it doesn't explicitly differentiate from siblings like trigger_scrub or pg_summary.

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

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

The description implies this is a read/reporting tool for scrub status, and the [READ] tag signals read usage. However, it gives no explicit when-to-use vs. alternatives like trigger_scrub/trigger_deep_scrub or pg_summary, so usage must be inferred.

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

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

Annotations already cover the mutation profile (readOnlyHint=false, destructiveHint=true), so the description's added value is the disclosure of risk level ('risk=medium') and, more importantly, that the operation is reversible to a prior state — which points the agent at the undo_list/undo_apply siblings. There is mild tension between 'Reversible' and destructiveHint=true, but the two describe different axes (mutation vs. undo support) and the description adds real context rather than restating the hints.

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: the risk/write tag and the core purpose appear in the first line, followed by a compact per-argument block. Every sentence carries information, and there is no filler or repetition of schema titles.

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 3-parameter write tool with annotations and no output schema, the definition covers purpose, all parameters, risk, and reversibility — enough to call it correctly. It does not say whether the change takes effect immediately or what happens on an invalid mode, but those gaps are minor at this complexity.

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% and the schema exposes no enum for mode, so the description carries the full documentation burden and does so: it gives the three legal mode values, sources pool_name from pool_ls, and explains target's default behavior ('omit for the default'). Without it the agent would have no way to know valid mode values.

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 — 'Set a pool's PG autoscale mode' — and enumerates the accepted values (on/off/warn), making the scope unmistakable. This is clearly distinct from the other set_pool_* siblings (quota, pg_num, size) without the agent 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?

Usage is implied rather than stated: it tells the agent where to get pool_name ('from pool_ls') and that the change is reversible to a prior state, but gives no explicit when-to-use/when-not guidance or sibling comparison. There is no statement of prerequisites or of what to do instead for related pool settings.

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

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

Annotations already declare the mutation profile (readOnlyHint=false, destructiveHint=true, idempotentHint=false), but the description adds genuinely new context: a [WRITE][risk=medium] tag and, importantly, that the change is reversible to the prior pg_num (matched by the undo_list/undo_apply siblings). This is useful beyond what annotations 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?

Front-loads the mutation/risk tags and one-line purpose before a scannable Args block. Every line carries 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 destructive, non-idempotent 3-param mutate tool with no output schema, the description covers purpose, risk, reversibility, and every parameter. It could go further on consequences (data rebalancing load, health-state preconditions), but is largely 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 coverage is 0%, so the description carries the full burden, and it documents all three parameters: pool_name (with its source tool), pg_num (new placement-group count), and target (Ceph target name, omit for default). It only omits validation detail such as pg_num power-of-two expectations.

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 ('Set a pool's pg_num'), naming the exact configuration field being mutated. This clearly separates it from sibling setters such as set_pool_size, set_pool_quota, and set_pool_autoscale.

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: 'pool_name (from pool_ls)' hints that pool_ls must be called first to discover a valid name, and target notes 'omit for the default'. There is no explicit statement of when to prefer this over set_pool_autoscale or any prerequisite about cluster health before rebalancing.

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 write/non-idempotent/destructive, and the description still adds real value by flagging risk=medium and stating the change is reversible back to the prior quota. It stops short of saying whether both quotas apply together or what errors occur for a nonexistent pool. The 'reversible' claim sits in mild tension with destructiveHint=true but does not flatly contradict it, since a too-small quota can effectively block writes.

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 operation tags, then a one-line purpose and a tight Args block. Every line adds information; nothing is redundant 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 4-parameter mutation with no output schema, the description covers intent, parameter semantics, and reversibility. Minor omissions remain: it does not say whether a confirmation or the resulting quota is returned, nor behavior when pool_name is invalid.

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: it gives pool_name's provenance (pool_ls), the 0-clears semantics for both max_bytes and max_objects, the omit-leaves-unchanged behavior, and the default meaning of target. This compensates completely 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?

"Set a pool's byte/object quota" is a specific verb+resource, and the byte/object qualifier cleanly separates it from siblings like set_pool_size, set_pool_pg_num, and set_pool_autoscale. An agent can identify the right 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?

It points to pool_ls as the source of pool_name, which is useful cross-tool guidance, and explains when to pass 0 versus omitting a quota. However, it never states when to reach for this tool versus set_pool_size or set_pool_autoscale, so selection guidance is only implied by the resource name.

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 destructive=true, readOnly=false, idempotent=false, so the safety profile is covered. The description adds substantial context beyond them: mass data movement on a live pool, reversibility to the prior size, the exact pools where reduction is refused, and that the guard applies under dry_run.

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 risk tag and the core action, then the preview/reversibility facts, then the refusal rules and Args. Every clause is informative, though the explanation of the mgr/REST-API cause is somewhat verbose for what it adds.

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 mutation with no output schema, the definition supplies everything an agent needs: safety profile via annotations, reversibility, preview path, and the full set of refusal conditions plus parameter meanings. No output schema exists, so return values need not be described.

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 coverage the description carries the full burden, and it documents all four parameters: pool_name (with a source pointer to pool_ls), size (new replica count), dry_run (preview semantics), and target (config name, omit for default). It lacks any constraint or range detail for the integer size, a small gap given 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+resource ('Set a pool's replica size') and immediately distinguishes itself from sibling pool mutators like set_pool_pg_num, set_pool_quota, and set_pool_autoscale. The '[WRITE][risk=high]' tag and the 'forces mass data movement on a live pool' clause give the agent the operation's character at a glance.

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

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

Explicitly says when to use it ('Pass dry_run=True to preview'), when it will refuse (size reduction on .mgr/.rgw.root and mgr-owned pools), and what is still allowed (raising size on those pools). It even notes the refusal is enforced under dry_run. The pool_name provenance ('from pool_ls') is 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 establishes the safe read profile, so the "[READ]" tag is largely redundant. The description does add real context by disclosing that output is decoded from the SLOW_OPS health check rather than raw Ceph output, but says nothing about permissions, cost, or result shape.

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?

Compact and front-loaded: the read tag and one-line purpose come first, the usage trigger second, and the lone parameter is documented in a short Args block. Every sentence earns its place.

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

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

For a single-optional-parameter read-only diagnostic with no output schema, the description covers purpose, trigger, and parameter behavior adequately. It would be fully complete if it hinted at what the returned per-OSD data looks like, but 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%, so the description must carry the parameter burden, and it does: "target: Ceph target name from config; omit for the default" explains both the meaning and the optional/default behavior. It could specify accepted target formats or where config names come from, but the core semantics are covered.

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 blocked/slow requests per OSD) and grounds it in a named data source (the SLOW_OPS health check), which distinguishes it from related diagnostics like pg_dump_stuck. An agent can tell what it returns 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?

"Use this to find the OSD sitting on blocked ops when clients report stalls" gives explicit trigger context for invoking the tool. It stops short of naming exclusions or alternative tools (e.g. pg_dump_stuck, osd_perf) for adjacent stall scenarios.

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 write/destructive/non-idempotent, and the description adds value beyond them by stating the change is reversible and that an undo record snapshotting the prior values is created. It also flags medium risk. It stops short of detailing auth requirements or side effects on in-flight recovery ops.

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/write tag and the core action are front-loaded, the rationale sentence is compact, and the arg list is tight with no redundant restatement of the schema. Every line earns its place.

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

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

For a 3-param mutation tool with no output schema and sparse annotations, the description covers purpose, trigger condition, mutability of each param, and rollback path. Remaining gaps are value ranges and any post-call verification guidance, both minor.

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

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

Schema description coverage is 0%, so the description must carry the burden, and it does: all three params are explained, including the 'omit to leave unchanged' semantics that are not expressed in the schema defaults. Units/ranges for the integer values are still 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 ('Tune') and names the exact config knobs (osd_max_backfills / osd_recovery_max_active) it mutates. This is unmistakably distinct from read-only siblings like osd_perf or cluster_status.

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 when-to-use scenario: turn backfill/recovery down when a recovery storm starves client IO, or back up once it's calm. It does not name an explicit alternative tool, but no sibling overlaps this tuning action, so context is sufficient.

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, idempotentHint=false and destructiveHint=true, and the description's [WRITE][risk=medium] tags are consistent with them. It adds that the scrub is a data-integrity operation, but says nothing about I/O load, expected duration, reversibility, or that the operation is asynchronous — all relevant for a non-idempotent mutation.

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?

Very compact: the risk/verb tags are front-loaded, followed by a one-line purpose and a two-item Args block where every line earns its place. 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?

No output schema exists, so the description could reasonably say what is returned (e.g., a task reference) and how to follow progress via scrub_status. It covers inputs and the write nature adequately but leaves the agent without guidance on monitoring or expected effect.

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 it does: it gives the pgid format with a concrete example ("2.1a") plus where to obtain it, and explains that target is a Ceph target name whose omission selects the default. This meaningfully exceeds 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 (schedule) and resource (deep/data-integrity scrub on a PG), and the 'deep' qualifier implicitly separates it from the sibling trigger_scrub. It stops short of explicitly naming that sibling or stating the contrast, so it is clear but not fully self-differentiating.

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 [WRITE][risk=medium] tag and the note that pgid comes 'from pg_summary / scrub_status', which helps the agent source the input. There is no explicit when-to-use/when-not guidance, no mention of when to prefer a shallow scrub (trigger_scrub), and no prerequisites such as required permissions or cluster state.

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 write/non-idempotent/destructive, and the description adds genuine context beyond them: a risk=medium qualifier, the async nature implied by "Schedule", and the concrete effect of clearing a specific warning. It stops short of describing permissions, failure behavior, or what state is altered.

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 [WRITE][risk=medium] tags, then a one-line purpose, then Args. No filler sentences, and the most important qualifiers appear first.

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 and no annotations covering the outcome, the definition is adequate but leaves gaps: nothing about whether the scrub runs synchronously, how completion is observed, or what authorization is required. The args and safety profile are covered, the operational contract is not.

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 load and does so well: pgid gets a concrete example ("2.1a") and its source tools (pg_summary / scrub_status), and target is explained as a config name with the omit-for-default rule. This meaningfully exceeds 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 and resource ("Schedule a shallow scrub on a PG") plus the observable outcome ("clears a PG_NOT_SCRUBBED warn"). The word "shallow" implicitly scopes it against the sibling trigger_deep_scrub, though the sibling is not 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?

The parenthetical about clearing a PG_NOT_SCRUBBED warn implies when the tool is warranted, but there is no explicit when-to-use vs when-not, and no routing to trigger_deep_scrub or the mention of prerequisites. Usage must be inferred.

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?

Annotations only supply readOnlyHint=true; the description goes well beyond that by disclosing the return shape, that truncation is *measured* via an extra-row fetch, and that effectVerified=false means the reversed change is only PROBABLE, with a caution to check live state and not over-report. This is meaningful operational context the 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-loaded with purpose and the sibling handoff, then structured paragraphs for return value and the effectVerified caveat. Every sentence carries information, though the emphasis on truncation being 'measured, not guessed from a length coincidence' is slightly verbose for the value it adds.

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 JSON shape, the meaning of every field an agent must act on (returned, limit, truncated, effectVerified), and the follow-up behavior for truncation. Nothing needed to call or interpret 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% and no param has an enum, so the description must compensate, and it does fully: limit is documented as default 50 / capped at 500, and target is documented as ignored with the reason (host-local undo state, kept for CLI uniformity).

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 recorded, not-yet-applied undo tokens') plus ordering ('most recent first'). The [READ] tag and the reference to undo_apply make it clearly distinguishable from the sibling that actually applies tokens.

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 the undoId with undo_apply.' and tells it to re-run with a higher limit when truncated rather than reporting a partial list as complete. It lacks an explicit 'when not to use this' condition, 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.