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

In the absence of annotations, the description fully discloses behavior: it is a pure arithmetic read projection, no clock read, no side effects. The [READ] prefix and explicit mention of deterministic arithmetic ensure transparency.

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 concise, with a clear first sentence summarizing purpose, followed by usage conditions and an Args section. Every sentence adds value without redundancy.

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

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

Although there is no output schema, the description hints at the output: capacity usage and daysToNearfull, with insufficient-data when growth is missing. It could be more explicit about the response format, but it is sufficient for a simple tool with two optional parameters.

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 compensates fully. It explains the effect of each parameter: daily_growth_bytes for projection vs. usage-only, target for Ceph config. This adds significant meaning beyond the schema's null defaults.

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

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

The description explicitly states it is a READ tool for capacity usage and a deterministic days-to-nearfull projection. It clearly distinguishes itself from sibling tools like osd_df (current usage) and cluster_health (overall health) by focusing on forecast and threshold definition.

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 when to use the daily_growth_bytes parameter: pass it for projection, omit for usage-only view. It defines nearfull as 85% and notes that without growth data, the forecast returns insufficient-data. However, it does not explicitly compare to alternatives like pool_df or osd_df, but the unique functionality makes the usage clear enough.

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]' prefix and description of surfacing status clearly indicate a read-only operation with no side effects. While no annotations are present, the description adequately conveys non-destructive behavior. A higher score would require explicit mention of safety or lack of mutations.

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 concise paragraphs with a clear header, details, and an 'Args' section. Every sentence adds value without redundancy.

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

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

The description lists what information is surfaced (rank state, client/standby counts, flag), which is helpful given no output schema. However, it does not specify the format (e.g., list, dictionary) or whether pagination applies, leaving minor ambiguity for tool invocation.

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

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

The only parameter 'target' has zero schema description coverage. The description adds value by explaining it is a Ceph target name from config and that omitting uses the default. This fully compensates for the schema's lack of description.

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?

Description clearly states it reads per-filesystem MDS ranks with specific status fields including the 'MDS behind on trimming' flag. This distinguishes it from sibling tools like cluster_status or mon_status 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?

Provides context for use by highlighting the 'notorious' flag that precedes metadata stalls, implying use when investigating metadata performance. However, it does not explicitly state when to avoid this tool or name alternatives among siblings.

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

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

With no annotations, the description carries full responsibility. It discloses the risk level ('[risk=medium]'), that it is a write operation, and that it is reversible with an undo record. This gives an agent sufficient awareness of side effects and reversibility, though it doesn't detail potential permission requirements or edge cases.

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 efficient and well-structured. The purpose and usage context are front-loaded, followed by a concise bulleted argument list. No wasted words, and the key information is immediately accessible.

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 flag toggle with no output schema, the description covers all essential aspects: purpose, usage, parameters, and behavioral details (reversible). It doesn't discuss error handling or preconditions, but these are minor given the tool's simplicity. Overall, an agent can call it correctly with the provided information.

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

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

Schema coverage is 0%, so the description must fully compensate. It does: each parameter is explained with examples and clear semantics (flag names, enable toggling, target defaulting). This adds significant value beyond the bare schema, making the parameters unambiguous.

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 clearly states the action (set/unset), the resource (cluster flag), and provides concrete examples (noout, nobackfill, etc.). It is distinct from sibling tools like set_pool_* which modify pool settings, so an agent can identify the correct tool.

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

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

It gives a specific usage context: 'Heavily used before maintenance (e.g. set noout while rebooting a host).' This tells the agent when to invoke it. It doesn't explicitly state when not to use it, but the context implies a maintenance scenario and no alternatives are needed since it's the only flag-toggle tool among siblings.

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

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

Without annotations, the description must disclose behavioral traits. It marks the operation as [READ] and describes the output format (plain-language cause + action). However, it does not mention permissions, rate limits, potential latency, or error handling. The disclosure is adequate but not exhaustive.

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

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

The description is concise and front-loaded with the purpose. The first two sentences convey the core functionality and usage guidance. The parameter description is brief but sufficient. No unnecessary fluff; the example codes add clarity without excessive verbosity.

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

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

Given no output schema, the description hints at the return format (cause + action per check) but does not detail the exact structure, error handling, or whether raw status is also included. For a tool with one optional parameter, it is mostly complete but leaves some gaps about the output.

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

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

The input schema has 0% description coverage for the 'target' parameter. The description adds meaning by stating it is a Ceph target name from config and can be omitted for the default. This adds value beyond the schema, but could be more specific about the default value or format. It compensates for the schema gap partially.

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 clearly states the tool reads health status and provides plain-language cause and action per active check. It specifically says it decodes raw HEALTH_WARN/ERR codes, distinguishing it from siblings like cluster_status which may provide raw status. The verb 'read' and resource 'health status' are specific.

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 explicitly recommends calling this tool first for cluster health questions and explains it decodes raw codes. It does not list alternatives or when not to use, but the guidance is clear enough for the primary use case. Sibling tools like osd_df or pool_df are for specific sub-components, so the 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?

The description explicitly marks the operation as '[READ]', indicating no side effects. With no annotations provided, this is a key behavioral disclosure. However, it does not cover potential performance impact or permissions needed, which is acceptable for a simple read tool.

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

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

The description is extremely concise, using only three lines with no redundant words. The purpose is front-loaded with the keyword '[READ]' and the function is clearly summarized.

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 tool with no output schema, the description lists the main fields it returns, which is adequate for understanding the output. It covers the essential context for a compact summary tool, though it could mention error states or scale limitations.

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

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

The single parameter 'target' is explained with its source ('from config') and its default behavior ('omit for the default'). This adds meaning beyond the schema's type/optionality, which had 0% coverage.

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 clearly states it is a compact summary of ceph -s, listing specific fields (mons, OSDs, PGs, etc.). The verb 'READ' and the content make it distinct from sibling tools like cluster_health or mon_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?

The description does not provide explicit guidance on when to use this tool versus alternatives. It implies it's for a quick overview, but lacks direct contrast with sibling tools or conditions for use.

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

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

No annotations provided, so description carries full burden. It indicates a read operation with no side effects, but lacks details on error handling, authentication, or potential outcomes when target is invalid. Basic transparency but could be improved.

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?

Description is concise with a clear header, explanation of what is retrieved, and parameter documentation. No unnecessary words, though slightly terse. Could benefit from a line break for readability.

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

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

Given the tool's simplicity (1 optional param, no output schema), the description adequately covers what the tool does and its single parameter. It lacks prerequisites or return format hints, but overall sufficient for a straightforward status read.

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 has 0% description coverage, so description adds value by explaining that 'target' is a Ceph target name from config and can be omitted for default. This provides context beyond the schema's type-only definition.

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?

Description clearly states it is a read operation to retrieve active mgr, its standbys, and enabled modules. The verb 'READ' is explicit, and the resource 'mgr' is specified. It distinguishes from siblings like mon_status or cephfs_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?

Description does not provide explicit when-to-use or when-not-to-use guidance. It implies usage for checking mgr status but no alternatives or exclusions. The context hints at usage for default or specified target, but no comparison to other status tools.

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 description marks itself as [READ] and explains what data it reveals (mons in/out of quorum, epoch). Without annotations, it carries the transparency burden and does so adequately. It does not mention permissions or additional side effects, but for a read-only tool this is sufficient.

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 extremely concise: a lead '[READ]' prefix, a brief purpose line, a use-case sentence, and a single parameter line. No wasted words, and the most important information is front-loaded.

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

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

Given the tool's simplicity (one optional parameter, no output schema, read-only), the description fully covers its purpose, when to use it, and the parameter. It is complete for an agent 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?

The description explains the sole parameter 'target' as 'Ceph target name from config; omit for the default.' This adds meaning beyond the minimal schema (which lacks a description). With only one optional parameter, this is clear and sufficient.

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 clearly states the tool monitors quorum status (mons in/out of quorum and monmap epoch). It uses a specific verb 'Monitor' and resource 'quorum', and distinguishes from siblings like mgr_status, osd_tree, etc., by focusing on monitor-specific health flags (MON_DOWN, clock-skew).

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 explicitly states when to call: 'when health flags MON_DOWN or a clock-skew warn'. It implies usage context but does not explicitly name alternative tools for comparison, missing a full when-not-to-use guide. However, the guidance is clear and actionable.

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

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

With no annotations, the description must fully convey behavior. It states it is a read operation and describes the output format, but does not discuss potential permissions, data source, or any side effects. Adequate but not comprehensive.

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 very concise, using only two lines plus the parameter note. It front-loads the purpose with '[READ]' and avoids any filler, earning its place.

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

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

Given the tool's simplicity (one optional parameter, no output schema), the description gives a good sense of the results: sorted OSD utilization with flags. Slightly abstract on exact output fields, but reasonable for a listing utility.

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

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

The schema has 0% description coverage for the single parameter. However, the description adds 'target: Ceph target name from config; omit for the default,' which provides context beyond the schema's type definition.

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 starts with '[READ]' indicating a read operation, and clearly states it lists 'Per-OSD utilisation (most-full first) with near/backfill-full flags.' This distinguishes it from sibling tools like osd_tree or osd_perf, making the purpose unambiguous.

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

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

No guidance is provided on when to use this tool versus alternatives (e.g., osd_tree, osd_perf). The target parameter is described, but there is no mention of prerequisites or context for choosing this tool.

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 description includes [WRITE] and [risk=medium] tags indicating a mutagenic operation with moderate risk, but does not detail prerequisites, reversibility, or potential side effects. Without annotations, more transparency would be beneficial.

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 extremely concise: one sentence plus an Args block with no unnecessary words. It is front-loaded with the action and risk tags.

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?

The description covers purpose and parameters adequately, but lacks usage guidance, behavioral depth (e.g., prerequisites, failure modes), and any mention of output, leaving gaps for a medium-risk write operation.

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?

Given 0% schema description coverage, the description adds essential meaning: osd_id is a numeric OSD ID from osd_tree, and target is an optional Ceph target name. This compensates for the schema's lack of parameter descriptions.

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

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

The description clearly states 'Mark an OSD in (return a drained/repaired OSD to service)' with a specific verb and resource, and the sibling tool osd_mark_out provides context for 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 description implies usage after draining or repairing an OSD but lacks explicit when-to-use or when-not-to-use guidance, nor does it mention alternatives beyond the operation itself.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly marks the operation [WRITE][risk=high], states it is 'Destructive to redundancy', and mentions specific risks like recovery storm and min_size. It also tells the agent how to preview safely.

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 with the risk warning, and then efficiently documents each argument. Every sentence earns its place, and the format makes the safety-critical warning immediately visible.

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 3-parameter tool with no output schema, the description is nearly complete: it warns of side effects, provides a preview path, and documents all arguments. It could optionally mention reversibility via osd_mark_in or how to verify completion, but nothing essential for safe 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 compensate, and it does. Each parameter gets meaningful semantics: osd_id is a numeric OSD id from osd_tree, dry_run controls preview behavior, and target names a Ceph config target with an omit-for-default default. This goes far beyond the bare type declarations.

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

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

The description opens with a specific verb and resource: 'Mark an OSD out'. It explains the operational consequence ('drains its data') and distinguishes the action from related tools like osd_mark_in or osd_purge by emphasizing the redundancy and recovery risk.

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 gives clear operational guidance — use dry_run=True to preview before committing — but it never explicitly explains when to choose this tool over siblings such as osd_mark_in or osd_reweight. The 'when to use' is implied rather than stated, and there are no exclusions or alternatives named.

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

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

No annotations are provided, so the description must disclose behavioral traits. It marks the tool as read-only with '[READ]' but does not explain what commit/apply latency entails, required permissions, or output format. The description is minimal for a tool with no annotation support.

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 extremely concise with a one-line summary and a one-line parameter explanation. Every sentence serves a purpose with no fluff, making it efficient for an AI agent to parse.

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

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

Given the simplicity of the tool (one optional parameter, no output schema), the description is still incomplete. It does not describe the output format or what values (e.g., avg, max latency) are returned. This lack of context could hinder an agent's ability to use the output correctly.

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

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

The input schema has 0% description coverage, but the tool description adds a brief explanation of the 'target' parameter ('Ceph target name from config; omit for the default'). This provides some value beyond the schema, but lacks detail on valid values or default behavior.

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 clearly states the tool reads per-OSD commit/apply latency, sorted slowest first, to find the slow disk. It uses a specific verb and resource, and is distinct from siblings like osd_df or osd_tree.

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

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

No explicit guidance on when to use this tool versus alternatives. The description does not mention when not to use it or suggest other tools for similar tasks, which is a gap given the large number of sibling tools.

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

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

With no annotations, the description carries the full burden and does so: it flags '[WRITE][risk=high]', calls the operation 'Irreversible', and enumerates the exact system changes (destroy + crush rm + auth del). It also mitigates risk by offering dry_run, adding critical behavioral context.

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

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

Compact and front-loaded: the risk marker and core action appear first, followed by dry-run and drain guidance, then a tight args list. Every sentence adds necessary information with no filler.

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

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

For a high-risk mutation with no annotations and no output schema, the description covers required state (drain before purge), preview mechanism, exact effects, irreversibility, and all parameters. Nothing needed to call it safely is missing.

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

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

Schema coverage is 0%, so the description must explain each parameter, and it does: osd_id is a numeric OSD id from osd_tree, dry_run controls preview vs actual purge, and target is an optional Ceph target from config with default behavior. The value goes well beyond 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: 'Purge an OSD', and lists the exact destructive steps ('destroy + crush rm + auth del'), making the operation unambiguous. It is clearly distinct from sibling tools like osd_mark_in/osd_mark_out and osd_reweight, which are non-destructive lifecycle 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 explicit operational guidance: 'Pass dry_run=True to preview' and 'Drain first (osd_reweight 0 → mark out → wait active+clean) before purging'. This tells the agent the safe invocation flow and prerequisites, which is more than most sibling definitions provide.

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?

Despite having no annotations, the description discloses the write nature with '[WRITE]', risk level 'medium', reversibility ('Reversible → prior weight'), and the dry-run preview behavior. It goes beyond the schema and gives the agent a clear picture of side effects and safety.

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 tightly structured and front-loaded: starting with tags, then a one-sentence summary, reversibility note, dry-run note, and a clean Args list. Every sentence adds value 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?

For a 4-parameter mutation tool with no output schema and no annotations, the description covers parameters, side effects, reversibility, and usage examples. It lacks explicit prerequisites or error conditions, but the essential information for calling the tool correctly 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?

The schema provides only types and defaults with zero property descriptions, so the description must compensate. The 'Args' section fully explains each parameter: osd_id source, weight range and drain semantics, dry_run behavior, and target configuration. This is meaningful beyond the schema.

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

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

The description clearly states a specific action: 'Set an OSD's reweight (0.0 drains it)' with the target resource identified. It also includes the key effect and reversal, making it distinct from sibling tools like osd_mark_out or osd_purge.

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 usage context through dry_run and the drain behavior, but it does not explicitly state when to choose this over alternatives like osd_mark_out or osd_purge. There is no direct when-to-use or when-not-to-use guidance, though the '0.0 drains it' hints at a common scenario.

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

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

No annotations exist, so the description carries the burden. It declares a read operation ('[READ]') and lists output fields, but fails to mention any behavioral traits like permissions, idempotency, or potential side effects. Adequate but not detailed.

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 concise: two lines plus an args section. Front-loaded with '[READ]' and main purpose. 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?

Despite no output schema, the description lists key output fields, providing partial completeness. However, it does not mention the tree structure or differentiate from other OSD tools like osd_df, leaving some gaps for a tool with many siblings.

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 compensates by explaining the 'target' parameter: 'Ceph target name from config; omit for the default.' This adds meaningful context beyond the schema's type-only definition.

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 clearly states it reads all OSDs and lists specific fields (up/in state, weight, host, device class). The verb '[READ]' and resource are specific, and it implicitly distinguishes from mutation tools like osd_mark_in or 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?

No explicit guidance on when to use this tool vs alternatives like osd_df or osd_perf, nor any exclusions or prerequisites. The description only implies a read operation but provides no context for selection.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly marks the tool as read-only with '[READ]' and documents the exact return shape, including the truncated flag semantics. This goes beyond a minimal description, though it does not mention error cases or performance implications.

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 compact and well-structured: it opens with the tool's purpose, then gives usage guidance, return format in a code block, and parameter explanations. Every sentence adds value and there is no redundant content.

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

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

Given there is no output schema, the description thoroughly explains the return value, including the truncated flag and limit field. It also covers both parameters and their defaults. For a two-parameter diagnostic tool, this is complete and leaves no critical gap for an AI agent.

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 explain all parameters. It does so completely: target is described as a Ceph target name from config with an omit-for-default instruction, and limit is described as the maximum stuck-PG rows to return with its default. This is exactly the semantic information an agent needs to call the tool correctly.

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

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

The description states a specific verb and resource: it dumps stuck PGs (inactive/unclean/stale/undersized/degraded) and surfaces implicated OSDs. This clearly distinguishes it from sibling tools like pg_summary or cluster_health by focusing on stuck PG diagnosis. The '[READ]' prefix also signals the operation type.

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 gives an explicit trigger condition: 'Use this when a PG is not recovering — it surfaces the OSD ids to investigate.' This tells the agent when to invoke the tool. It does not explicitly name alternatives or exclusions, but the context is clear enough to route correctly.

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

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

With no annotations, the description carries the full behavioral burden and does so well. It declares this is a READ operation, explains that unhealthyCount is the true total, states that the unhealthy list is capped at limit, and reveals the truncated: true behavior. This goes well beyond the minimal 'returns a summary' explanation.

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 compact, front-loads the core behavior, and every sentence earns its place. The truncation caveat is critical and placed at the point where it is most useful, followed by a clean Args section.

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 summary tool with two optional parameters and no output schema, this description is complete. It gives the agent enough to select the tool, invoke it correctly, interpret the key output fields, and know the truncation caveat.

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 explain both parameters. It does: target is 'Ceph target name from config; omit for the default', and limit is 'Maximum unhealthy PG rows to return. Default 200.' This fully compensates for the empty schema descriptions.

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

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

The description opens with a specific scope: 'PG state histogram + every PG that is not active+clean' and maps it to the question 'are my PGs healthy?'. This clearly distinguishes it from sibling tools like osd_tree or pg_dump_stuck by naming the exact resource and state filter.

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 explicitly says 'Call this to answer "are my PGs healthy?"' and adds operational advice about re-running with a higher limit for truncated results. It does not name alternatives or exclusions, so it stops short of a 5, but the context is clear.

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

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

The description includes a '[WRITE][risk=medium]' tag, which provides some behavioral context. However, it does not disclose side effects, conflict behavior, or permission requirements. Since no annotations are provided, the description partially compensates but leaves gaps.

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 concise, with a clear structure: a header line followed by a list of arguments with explanations. No unnecessary words 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?

The description covers parameters well and the write operation is clear. It does not describe return values, but overall it provides sufficient context for a straightforward creation tool. Minor improvement could be a note on typical output.

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

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

The description explains all 5 parameters with details (defaults, application options), providing significant meaning beyond the input schema which has 0% description coverage. This fully compensates for the schema gap.

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

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

The description clearly states 'Create a replicated pool', which is a specific verb and resource. It distinguishes from sibling tools like pool_delete, pool_ls, and set_pool_pg_num, as it is the only creation tool.

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

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

No explicit guidance on when to use or when not to use. The purpose is clear but lacks context about prerequisites or scenarios where alternatives are preferable. Usage is implied by the create action.

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

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

With no annotations provided, the description carries the full burden and excels. It discloses that deletion is irreversible, that dry_run is enforced even for protected pools, and explains the cascading consequence of deleting the mgr-owned pool on every later call. This goes well beyond the minimal 'delete a pool behavior.

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 front-loaded with the most critical warning first, followed by safe usage pattern, guardrails, and then parameter docs. Every sentence earns its place; the repetition of irreversibility reinforces the danger without bloating the 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?

Given the destructive nature, lack of annotations, and absence of an output schema, the description covers everything needed to call it correctly: safe preview, protected pools, parameter sources, and downstream consequences. No critical context is missing for an agent to make an informed invocation.

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 compensate, and it does. It adds meaning to each parameter: pool_name comes from pool_ls, dry_run controls preview mode, and target refers to a Ceph target from config with an explicit 'omit for the default' instruction. This is exactly the clarity the schema lacks.

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

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

The description opens with a specific verb and resource: 'Delete a pool — destroys all of its data.' It clearly differentiates itself from sibling tools like pool_create and set_pool_* by emphasizing irreversibility and data destruction, leaving no ambiguity about what the tool does.

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 gives practical guidance: use dry_run=True to preview, and it warns that .mgr/.rgw.root and mgr-owned pools are refused because deleting them severs the transport. It does not explicitly name an alternative tool, but the exclusion criteria and safe-invocation workflow provide strong 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?

With no annotations, the description carries the full behavioral disclosure burden and does well by labeling the tool as [READ] and explaining the error semantics in detail. The warning that a non-null error means query failure rather than 'no pools' is valuable because it prevents a common misinterpretation. It stops short of mentioning permissions or other operational constraints, but for a read-only query this is largely sufficient.

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 compact and front-loaded: a one-line purpose, then return format, then a crucial error-handling note, then the single parameter. Every sentence earns its place, and the error clarification is high-value rather than 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 simple one-parameter read tool with no output schema and no annotations, the description covers the return structure, error behavior, and parameter meaning. It could elaborate on what 'returned' represents or what the pool objects contain, but the essentials for correct invocation and interpretation are present.

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

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

The schema only provides the parameter title 'Target' with 0% description coverage, so the description must add meaning. The line 'Ceph target name from config; omit for the default' explains the source and optionality of the parameter, which is helpful. It still leaves the actual default target unspecified, but this is enough for correct invocation in most contexts.

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 clearly states the tool reads per-pool usage metrics (bytes, percent, objects, capacity), which is a specific and useful purpose. It does not explicitly name siblings like osd_df or pool_ls to differentiate them, though 'per-pool usage' is distinct enough to be reasonably clear.

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 provides no explicit guidance on when to choose this tool over alternatives such as osd_df or pool_ls. There is no mention of use cases, exclusions, or sibling routing, so an agent must infer when this tool is appropriate solely from the stated purpose.

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 description labels the tool as '[READ]' indicating it is non-destructive and lists the fields returned. However, it lacks additional behavioral context such as performance implications, authorization requirements, or rate limits.

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

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

The description is extremely concise, with two short sentences that convey the purpose and parameter information without redundancy.

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

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

Given the tool's simplicity and lack of output schema, the description covers the main functionality and output fields. It does not address potential filtering or pagination, but these may not be critical for this operation.

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

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

The only parameter 'target' is described as 'Ceph target name from config; omit for the default.' This adds meaning beyond the schema's type definition, especially since schema description coverage is 0%.

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 starts with '[READ]' and explicitly states 'All pools: size/min_size, pg_num, autoscale mode, application, quota.', clearly identifying it as a read-only listing tool. It distinguishes itself from sibling tools like pool_create, pool_delete, etc.

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 explicit guidance on when to use this tool versus alternatives. The description mentions an optional 'target' parameter but does not elaborate on scenarios or provide comparisons to sibling tools.

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

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

No annotations are provided, so the description must disclose behavioral traits. It mentions [WRITE][risk=medium] but does not describe failure modes (e.g., duplicate name, pool constraints), permissions, or side effects beyond creation. This leaves significant gaps for an agent.

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 extremely concise with a tag line and structured arg list. Every sentence adds value, no redundancy. Front-loaded with risk and action type.

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?

While the description covers purpose and parameters, it omits return values (no output schema) and behavioral context like idempotency or error handling. For a create tool, an agent may need to know what happens on success or failure.

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 compensates well by explaining pool_name ('from a pool listing'), name ('New image name'), size_bytes (unit), and target ('omit for the default'). This adds context beyond bare schema 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?

The description clearly states 'Create a new RBD image in a pool' with a specific verb (create) and resource (RBD image). It distinguishes from sibling tools like rbd_image_delete and rbd_ls, and includes a [WRITE][risk=medium] tag for context.

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 intended usage is implicit (create an image), but there is no explicit guidance on when not to use or alternatives among sibling tools. The description lacks when-to-use vs when-not-to-use language.

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

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

With no annotations provided, the description carries the full behavioral disclosure burden. It explicitly warns '[WRITE][risk=high]', states that deletion removes 'ALL its data', calls the operation 'Irreversible', and offers a dry-run preview, making the destructive side effects unambiguous.

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 tightly structured: a bold risk warning is front-loaded, followed by a single dry-run tip and a compact parameter list. Every sentence and line adds practical value, with no repetition or 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?

Given that there are no annotations and no output schema, the description provides all necessary context: purpose, irreversible data loss, preview mechanism, and parameter semantics. An agent can confidently decide whether and how to invoke this destructive operation.

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%, but the Args block adds meaningful semantics for every parameter: pool_name locates the image, image_name identifies the specific image from rbd_ls, dry_run controls preview behavior, and target explains how to select or default the Ceph target. This fully compensates for 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?

The description begins with 'Delete an RBD image and ALL its data', naming a specific verb, resource, and destructive scope. This clearly distinguishes it from sibling tools such as rbd_snapshot_delete or pool_delete, and the [WRITE][risk=high] marker reinforces its purpose.

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 gives clear operational guidance with 'Pass dry_run=True to preview' and notes that image_name should come from rbd_ls, establishing a workflow. It does not explicitly state when not to use this tool versus related deletion tools, but the intended context is clear.

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

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

No annotations provided, so description carries burden. It indicates read-only nature and output fields, but does not disclose any additional behaviors like permissions, rate limits, or response format. Basic transparency.

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 concise: two-line purpose followed by two-line parameter descriptions. No fluff, front-loaded with main purpose, every sentence adds value.

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

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

Given no output schema, description lists output fields (size, features, snapshot count) which helps agent understand return. Lacks details on formatting or limitations, but sufficiently complete for this simple list tool.

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

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

Schema description coverage is 0%, but the description adds clear meaning for both parameters: 'Restrict to a single pool name; omit for all pools' and 'Ceph target name from config; omit for the default.' Compensates well for missing schema 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?

The description clearly states 'RBD images' and lists output fields ('size, features, snapshot count'), with a '[READ]' prefix indicating read-only. This distinguishes it from sibling tools like 'pool_ls' or mutation tools.

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

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

Provides clear usage context: optionally restrict to a pool name or omit for all pools, and target from config or default. Does not explicitly state when not to use or alternatives, but the context is adequate.

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

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

With no annotations provided, the description carries the behavioral burden. It explicitly marks the operation as [WRITE][risk=medium] and explains reversibility via snapshot deletion, which is meaningful beyond the name and schema. It does not cover permission requirements or failure modes, but the key safety context is present.

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 compact, front-loaded with risk and operation tags, and uses a scannable Args block. Every sentence and parameter line earns its place without redundancy.

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

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

For a simple snapshot-creation tool with no output schema, the description covers all inputs and the reversibility of the operation. Minor gaps remain around duplicate snap_name handling and failure behavior, but these are not critical for correct invocation.

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?

Although schema description coverage is 0%, the description compensates by documenting all four parameters with actionable definitions, including the 'from rbd_ls' guidance for image_name and the default behavior for target. This adds real value beyond the schema.

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

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

The description states a specific verb and resource: 'Snapshot an RBD image.' This clearly identifies the operation and distinguishes it from sibling tools like rbd_snapshot_delete, rbd_image_create, and rbd_image_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?

The intended use is implied by the action and the hint 'Reversible → delete the snapshot,' which points toward the inverse operation. However, it does not explicitly name an alternative or state when to prefer this tool over related tools.

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

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

No annotations are provided, so the description carries the full burden of disclosing behavior. It states that deletion is irreversible, marks the operation as write/high-risk, and explains that dry_run previews without deleting. This goes well beyond the bare schema, though it does not describe return values or preconditions such as protected snapshots.

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 compact and well-structured: a one-line action and risk statement, a practical preview tip, and a clean Args list. Each sentence earns its place with 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?

For a simple but destructive delete operation, the description covers the action, all parameters, and the safest invocation pattern. It could be slightly more complete by noting prerequisites (e.g., snapshot protection/clone constraints) and success/error response expectations, but nothing essential to invoking the tool 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%, but the description compensates fully by explaining every parameter: pool_name, image_name, snap_name, dry_run, and target. It adds practical meaning beyond the schema titles, especially the default behavior for target and the preview semantics of dry_run.

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, unambiguous action: 'Delete an RBD image snapshot.' It also marks the operation as a write with high risk and notes irreversibility, which clearly distinguishes this destructive tool from read-only Ceph status siblings and from rbd_snapshot_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?

The description clearly indicates this is for deleting an RBD snapshot and provides a practical usage safeguard: 'Pass dry_run=True to preview.' It does not explicitly compare against alternative tools or state when not to use it, but the action and preview guidance give clear 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 description mentions 'Partial-safe if the bucket call fails', which adds behavioral context. However, without annotations, it fails to specify if the tool is read-only, required permissions, or other side effects. The 'READ' tag is informal and not part of annotations.

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

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

The description is succinct, with clear sections: a heading, operation description, safety note, and parameters. Each sentence adds value, though the structure could be slightly more formal.

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

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

Given the tool's simplicity (one optional parameter, no output schema), the description provides adequate context but lacks information about output format or return values. It mentions 'Flags buckets' but does not detail what the output looks like.

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

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

The description explains the only parameter 'target' in detail: 'Ceph target name from config; omit for the default.' This adds significant meaning beyond the schema, which only specifies type and allows null.

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 clearly states the tool performs a READ operation on RGW daemons and a large-omap scan to flag oversized unsharded bucket indexes. It distinguishes itself from sibling status tools by focusing specifically on RGW and a known performance issue.

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 usage for checking RGW health and large omap issues, but does not explicitly state when to use this tool versus alternatives or provide exclusion criteria. No guidance on prerequisites or scenarios to avoid.

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 description explicitly marks the tool as '[READ]' and explains it decodes PG_NOT(_DEEP)_SCRUBBED, indicating it is a read-only operation. However, without annotations, more detail on side effects or performance impact would be beneficial; the current description is basic but adequate.

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 extremely concise, with one line for purpose and one for arguments. It is front-loaded with '[READ]' and uses a clear format. Every sentence contributes necessary information without superfluous 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 simple read-only tool with one optional parameter, the description covers the core purpose and parameter adequately. It lacks details on return format or threshold for 'overdue', but given the tool's simplicity and no output schema, it is reasonably 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?

The schema provides no description for the 'target' parameter (0% coverage), but the description adds: 'Ceph target name from config; omit for the default.' This clarifies the parameter's meaning and default behavior, adding significant value beyond the schema.

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

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

The description clearly states '[READ] PGs overdue for shallow / deep scrub', specifying the verb and resource. It distinguishes from sibling tools like trigger_scrub and trigger_deep_scrub, which are action-oriented, and other status tools like pg_dump_stuck, which focus on stuck PGs rather than overdue scrubs.

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 usage for checking overdue scrub PGs but provides no explicit guidance on when to use this tool versus alternatives such as pg_dump_stuck or trigger_scrub. No exclusions or prerequisites are mentioned.

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 description includes [WRITE][risk=medium] indicating it's a potentially risky write operation and notes reversibility. However, it does not detail specific consequences of changing autoscale mode or required permissions, leaving some behavioral ambiguity.

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 extremely concise: one action sentence, a note on reversibility, and three bullet-pointed parameter descriptions. Every element is useful, no waste, properly front-loaded.

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

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

The description adequately covers parameters and risk, but omits any mention of the return value or success/failure response. For a simple setter, this is acceptable but could be improved by stating expected output.

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 compensates fully: explains pool_name source, enumerates allowed mode values ('on', 'off', 'warn'), and clarifies target's default behavior. This adds essential meaning beyond the schema's type-only definitions.

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 clearly states the tool sets a pool's PG autoscale mode with specific values (on/off/warn), using a specific verb-resource structure. It distinguishes from sibling tools like set_pool_pg_num or set_pool_size by exactly naming the autoscale feature.

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 explicit guidance on when to use this tool versus alternatives, no prerequisites or exclusions. The description only explains what the tool does, not the context of usage relative to other pool management tools.

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

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

No annotations are provided, so the description bears full responsibility for behavioral disclosure. It mentions '[WRITE]' and 'Reversible → prior pg_num', but fails to disclose important traits such as required permissions, potential data migration, or asynchronous behavior. This is insufficient for a mutation tool.

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

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

The description is extremely concise, with a one-line summary and a bulleted list of arguments. Every sentence serves a purpose, and there is no redundant or extraneous 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?

Given that this is a write operation with no output schema, the description lacks crucial details such as the return value, potential side effects (e.g., data rebalancing), and performance implications. The mention of reversibility is helpful, but overall the description is incomplete for a mutation tool.

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

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

The input schema has 0% description coverage, but the tool description provides explanations for all three parameters. It adds context like 'Pool name (from pool_ls)' and 'Ceph target name from config; omit for the default', which aids understanding beyond the raw 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 clearly states 'Set a pool's pg_num', which is a specific verb and resource. It distinguishes from sibling tools like set_pool_autoscale, set_pool_quota, and set_pool_size, which modify different pool properties.

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 does not explicitly provide when-to-use or when-not-to-use guidance. However, the tool name and description imply it is for adjusting placement group count, which differentiates it from siblings. No alternatives are mentioned, so the guidance is minimal.

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

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

With no annotations provided, the description bears full responsibility. It discloses the write nature ([WRITE]), risk level (medium), and importantly notes reversibility ('Reversible → prior quota'). However, it does not detail required permissions or potential side effects of modifying quotas, but the core behavioral traits are covered.

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 extremely concise, using a compact one-line tag followed by bullet-like parameter explanations. Every sentence adds value with no redundancy. The structure front-loads the key action and risk, making it easy to scan.

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

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

Given the tool's simplicity (no output schema, few parameters), the description is nearly complete. It covers the operation, parameter details, and a prerequisite hint. However, it could mention expected return values or confirmation behavior, but that is not critical for this tool.

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

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

Schema description coverage is 0%, so the description must fully explain parameters. It does so effectively: pool_name source from pool_ls, max_bytes/max_objects behavior (0 clears, omit unchanged), and target default. This adds significant meaning beyond the raw schema, clarifying default null semantics and usage of 0.

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 clearly states 'Set a pool's byte/object quota' with a specific verb and resource. It distinguishes this tool from sibling pool modification tools (e.g., set_pool_size, set_pool_autoscale) by focusing on quota management. The [WRITE][risk=medium] tag further clarifies the operation type.

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 usage context by stating 'Pool name (from pool_ls)' as a prerequisite, but it lacks explicit guidance on when to use this tool versus alternatives like set_pool_size or set_pool_pg_num. No when-not conditions or alternative tool comparisons are provided.

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

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

With no annotations provided, the description carries full behavioral burden. It discloses high risk, forces mass data movement, is reversible to prior size, supports dry_run, and enforces the refusal of size reduction on mgr-owned pools even under dry_run. This is exceptionally transparent about side effects and 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 description is longer than average but well-structured: a bolded risk prefix, a concise summary, detailed behavioral notes, and a clear Args section. It is front-loaded with the key point and risk. Every sentence adds value, though some minor redundancy exists (e.g., repeating refusal conditions in summary and details). Overall it's appropriately sized for a high-risk mutation.

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

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

Given the tool's complexity (high-risk, live cluster, conditional refusals), no annotations, and no output schema, the description is remarkably complete. It covers the operation's effect, reversibility, dry-run behavior, special pool restrictions, and all parameter semantics. An agent has enough information to invoke it correctly without additional research.

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 fully explain parameters. It does: pool_name is 'from pool_ls', size is 'New replica count', dry_run 'preview without changing', target 'Ceph target name from config; omit for the default'. This adds practical meaning beyond the bare schema types and defaults.

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

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

The description opens with a clear verb+resource: 'Set a pool's replica size'. It further specifies it operates on a live pool and forces mass data movement, which distinguishes it from sibling tools like set_pool_quota or set_pool_pg_num. Even without naming alternatives, the purpose is unambiguous and specific.

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 does not explicitly contrast with sibling tools or state when to choose this tool over alternatives. It does provide contextual guidance: dry_run for preview, and it warns against reducing size on mgr-owned pools. However, it lacks explicit 'when to use' / 'when not to use' guidance relative to other pool-setting tools, so guidance is implied rather than stated.

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

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

No annotations are provided, so the description carries full burden. It marks itself as a [READ] operation and explains it decodes a health check. However, it does not disclose potential side effects, required permissions, or behavior when no slow ops exist. The description is minimal but not misleading.

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 very concise: one-line summary, a usage sentence, and an Args section. It is front-loaded with the purpose and uses minimal verbiage. Every sentence adds value.

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

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

Given the simplicity of the tool (one optional param, no output schema), the description is complete enough. It states the purpose, usage context, and parameter meaning. It does not explain return format, but that is reasonable for a diagnostic tool without explicit output schema.

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

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

The only parameter 'target' is described as 'Ceph target name from config; omit for the default.' This adds meaning beyond the schema's name-only property, clarifying it's optional and comes from config. Schema coverage is 0%, so description compensates well.

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 clearly states it retrieves blocked/slow requests per OSD by decoding the SLOW_OPS health check. It specifies the resource (OSDs) and the context (clients report stalls). This distinguishes it from sibling tools like osd_perf or cluster_health.

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 explicitly says when to use: 'find the OSD sitting on blocked ops when clients report stalls.' It does not mention when not to use or list alternatives, but the context implies it's for diagnostic purposes among many Ceph monitoring tools.

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

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

With no annotations, the description must fully disclose behavior. It states the action is reversible (records undo) and marks risk as medium. However, it does not mention any side effects, authorization needs, or what happens if parameters are set too low/high. The reversibility is a strong point, but more could be said.

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 succinct and well-structured: a risk marker, a one-line summary, a usage context sentence, and a clear parameter list. Every sentence adds value without redundancy. It is appropriately front-loaded.

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

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

Given no output schema, the description covers the tool's purpose, when to use it, reversibility, and parameters. It lacks examples of typical values or error conditions, but for the complexity level (a tuning tool), it is fairly complete and aids an AI agent.

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. It explains each parameter: max_backfills, recovery_max_active, and target, noting that omitting leaves the setting unchanged. This adds critical meaning beyond 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?

The description clearly states it tunes osd_max_backfills and osd_recovery_max_active to control recovery/backfill storms. The verb 'tune' and resource are specific, though it does not explicitly differentiate from sibling tools, most of which are read-only or have different purposes. However, the context (Ceph recovery tuning) helps an AI agent understand its role.

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 gives explicit context: use it when a recovery storm is starving client IO or when it's calm (back up). It also notes reversibility, but does not mention when not to use it or list alternative tools. The guidance is clear and actionable.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It does include '[WRITE][risk=medium]', indicating the operation mutates state and carries some risk, and it notes this schedules a scrub rather than instantly performing a read. However, it does not describe side effects, permissions, reversibility, or what happens after scheduling, so full transparency is missing.

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 compact, front-loaded with the write/risk tag, then gives a one-line purpose and two clearly formatted argument explanations. Every sentence adds value, and the example is useful without bloating the 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 simple two-parameter tool, the description supplies enough to call it correctly: purpose, parameter meanings, example values, and default behavior. The main gaps are the lack of output/return behavior and more explicit side-effect information, but these are minor for a scheduling action with this level of argument detail.

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 description fully compensates: it explains pgid as a Placement group id with a concrete example and a source reference, and explains target as a Ceph config name with default behavior. This is exactly the meaning an agent needs beyond 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?

The description states a specific action: schedule a deep (data-integrity) scrub on a PG. It also distinguishes itself from the sibling trigger_scrub by making the 'deep' aspect explicit. The '[WRITE]' and 'risk=medium' prefix add further operational clarity.

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 gives clear context on how to use the tool: it tells the agent that pgid comes from pg_summary / scrub_status and that target should be omitted for the default. It does not explicitly state when not to use this tool versus trigger_scrub, so it stops short of a 5.

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

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

With no annotations, the description carries the full burden. It does declare '[WRITE][risk=medium]', indicating it's a mutation with moderate risk, and mentions it clears a warning. However, it does not disclose potential side effects, reversibility, permission requirements, or what happens if the scrub cannot be scheduled. This is 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?

The description is compact: two lines for the main action and a concise arg list. It front-loads the write/risk indication and uses efficient phrasing. No filler. It loses a point because the arg list could be formatted with clearer separators, but overall it is appropriately concise.

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

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

For a two-parameter write tool with no output schema, the description covers the main usage and hints at prerequisites (check pg_summary/scrub_status). However, it omits return values, error conditions, and any idempotency or concurrency notes. An agent can probably call it correctly but may be uncertain about the response format.

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 is the sole source of parameter meaning. It explains pgid with an example and source, and target with a clear instruction ('omit for the default'). This adds meaningful semantic value beyond the raw schema, though it could be slightly more detailed (e.g., format of 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?

The description states a clear action ('Schedule a shallow scrub on a PG') with a specific resource (PG) and effect (clears PG_NOT_SCRUBBED warn). The word 'shallow' explicitly distinguishes it from the sibling trigger_deep_scrub, so an agent can differentiate 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 gives some usage context, like where to obtain the pgid (from pg_summary / scrub_status) and that target can be omitted for the default. However, it does not explicitly state when to use this tool over trigger_deep_scrub or when not to use it. The distinction is implied by the term 'shallow' but not spelled out as a guideline.

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

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

With no annotations, the description carries full burden. It discloses dispatching the inverse tool, the governed execution, dry-run preview, and one-time token use. Lacks explicit mention of side effects like token consumption or error handling, but covers key behaviors.

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?

Five sentences with clear structure: purpose statement, behavioral details, parameter list. Front-loaded with '[WRITE][risk=medium]'. Every sentence adds value without redundancy.

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

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

Describes parameters and overall mechanism, but lacks output description or error conditions. With no output schema, the agent is left guessing the return value. Adequate for a simple tool but not 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 coverage is 0%, so description must compensate. It explains each parameter: undo_id source, dry_run purpose, and target pass-through. Adds meaningful context beyond schema types and defaults.

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

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

The description clearly states it applies a recorded undo by dispatching its inverse tool. It references undo_list as the source of undo IDs, distinguishing it from listing tools and other mutation tools like retry_pipeline or cancel_pipeline.

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

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

Provides context for use: apply undo from undo_list, preview with dry_run, and notes that each token can only be applied once. Does not explicitly list when not to use or alternatives, but the implicit guidance 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?

With no annotations provided, the description carries the full burden and does so excellently. It discloses the return shape, the measured rather than guessed truncation behavior, the meaning of effectVerified, and the fact that target is unused, plus the limit cap.

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 front-loaded with the core purpose, then structured into return semantics, caveats, and parameter documentation. Each sentence adds unique value; no filler or redundant restatement.

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

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

Given no output schema and no annotations, the description supplies a complete picture: return format, parameter behavior, truncation semantics, verification caveats, and how to proceed with undo_apply. An agent has everything needed to call and interpret the tool 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 must document parameters itself. It fully explains limit's default and cap and explicitly states that target is accepted but unused for CLI uniformity. This goes well beyond what the bare schema provides.

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

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

The description opens with a specific verb and resource: 'List recorded, not-yet-applied undo tokens (most recent first).' It clearly differentiates from the sibling undo_apply by describing the inspection role rather than the application role.

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

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

It gives clear context for when to use the tool: when you need to see pending undo tokens before applying one. It also tells the agent to use the returned undoId with undo_apply and to re-run with a higher limit when truncated is true. It does not explicitly name alternatives or exclusions, but the guidance is sufficiently clear.

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