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

Beyond the annotations, it discloses the risk tier, the reversibility path, and an unusual safety caveat: canned policies replace rather than add, so the call can silently narrow the tool's own credential and is refused in that case. That is exactly the kind of non-obvious behavior annotations cannot express (destructiveHint=true alone doesn't convey replace-semantics or the self-refusal).

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

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

Front-loaded with [WRITE][risk=medium] and the reversibility note, followed by the single most important behavioral caveat, then a compact Args list. No sentence is redundant given the zero schema coverage.

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

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

Covers safety, reversibility, and every parameter despite no output schema and thin annotations. The one gap is that it doesn't clarify what happens to policies already attached to the user (the replace-semantics note is framed around the tool's own credential, not the target user).

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

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

Schema description coverage is 0%, so the description carries the full burden — and it documents all four parameters, including provenance hints (access_key from iam_users, policies from iam_policies), the default behavior of omitting target, and the semantics of dry_run as a preview.

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 ("Attach canned policies to a user") and immediately names the inverse sibling operation ("Reversible → detach"), which is enough to distinguish it from detach_user_policy and the other iam_* tools without opening a schema.

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

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

Gives a clear context cue (attach vs. the detach alternative) and mentions dry_run as a preview path, plus the credential self-refusal case. It does not spell out when-not to use this versus siblings like create_user or set_user_status, so it stops short of full when/when-not guidance.

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

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

Annotations declare destructiveHint=true and idempotentHint=false, and the description adds substantial context beyond them: the server force-enables versioning as a side effect, the result reports observed rather than assumed state, and undo is only possible while the bucket is empty. The "Reversible" claim is backed by the concrete undo mechanics rather than left vague, so it does not conflict with the destructive annotation.

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

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

Front-loads the write/risk tag and action, then pays out only the non-obvious facts (object-lock immutability, forced versioning, empty-bucket undo) before a self-contained Args block. The only mild redundancy is restating object-lock immutability in the Args section, which is defensible for a standalone parameter list.

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 a mutation tool with no output schema, the description covers naming rules, WORM implications, dry-run behavior, target selection, and undo limits. It does not say what happens on a name collision (bucket already exists), which matters since idempotentHint=false and the schema has no such parameter.

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

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

Schema description coverage is 0%, so the description carries the full burden and does: bucket_name gets format constraints (3-63 chars, lowercase/digits/dots/hyphens), object_lock is flagged as immutable after creation, dry_run is described as a preview, and target is identified as a config-defined MinIO target with a documented default.

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

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

Opens with a specific verb+resource ("Create a bucket") plus a distinguishing attribute ("optionally WORM-capable"), which separates it from siblings like bucket_delete, bucket_lock_config, and set_versioning. An agent knows immediately this is the creation entry point.

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

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

Explicitly states that object_lock=True is the ONLY way to obtain object lock because S3 has no later call that enables it, which routes the agent away from sibling tools such as bucket_lock_config or set_default_retention for that goal. It also documents the undo path (delete while empty) and the dry_run preview option.

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

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

Annotations already declare destructiveHint=true, but the description adds substance beyond them: irreversibility, the verifiably-empty precondition, the scope of the emptiness check, and the no-mass-delete guarantee. This is exactly the behavioral context an agent needs before an irreversible operation.

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

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

Front-loaded with [WRITE][risk=high] and the irreversibility warning, then usage guidance, then args. No sentence is filler; even the emptiness-check sentence earns its place by preventing an agent from assuming it can force-delete.

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

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

For a high-risk mutation with no output schema and zero schema coverage, the description covers safety, precondition, preview path, parameter provenance, and target resolution. Nothing an agent needs in order to call it correctly is missing.

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

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

Schema description coverage is 0%, so the description must compensate, and it does: bucket_name's provenance is given (from bucket_ls), dry_run's preview semantics are defined, and target's fallback to the default is explained. Every parameter gains meaning unavailable in 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 (Delete) and resource (a bucket), plus a crucial behavioral constraint: it is refused unless verifiably empty. This distinguishes it from bucket_create and from sibling object-level deletion paths; an agent knows exactly what this 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?

Explicitly offers dry_run=True to preview before committing, and states the tool will never mass-delete to force a bucket empty. It also tells the agent that noncurrent versions and delete markers count toward emptiness, which shapes when to use remove_incomplete_uploads or object-level cleanup first.

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

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

With readOnlyHint already declaring a safe read, the description adds meaningful behavioral detail: findings are ranked riskiest first and include cause plus action, and the scan covers multiple specific bucket exposure conditions. It does not discuss permissions, pagination, or performance limits, but it goes well beyond the annotation.

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

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

The description is front-loaded with the purpose and scan scope, then gives a compact Args section. It is efficient, though the multi-line formatting and repeated default values add slight verbosity without harming comprehension.

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 audit tool with two optional parameters and no output schema, the description covers the scan scope, ranking behavior, and return shape at a summary level. It is complete enough to invoke correctly, with minor remaining gaps around exact output fields and pagination.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It documents both optional parameters: limit as maximum buckets to audit with default 100, and target as an optional MinIO target from config with default behavior when omitted.

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 audit action on buckets and enumerates exactly what is checked: anonymous/public policy statements, missing default encryption, versioning off, and no lifecycle. This gives an agent enough to distinguish it from siblings like bucket_info, lifecycle_gap_analysis, or diagnose_iam_exposure.

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 frames the tool as 'the fastest answer to "is anything in my object storage exposed?"', which clearly signals the intended use case. It does not explicitly exclude nearby siblings or name alternatives, but the context is strong enough for correct 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?

readOnlyHint=true already declares this as a safe read, and the '[READ]' tag reinforces it without contradicting. The description adds useful context that a single call returns multiple config domains at once, but discloses nothing about error behavior (e.g., unknown bucket), required permissions, or response shape.

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

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

Front-loads the one-line purpose before the Args block, and every line is short. The Args block slightly duplicates structured schema fields, but since the schema has zero descriptions it earns its place.

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

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

For a read-only info tool with no output schema and minimal annotations, the description conveys scope, the config sections returned, and both parameters. Remaining gaps (error/failure behavior, auth requirements) are minor for this tool class.

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

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

Schema description coverage is 0%, so the description carries the parameter burden and does so well: it explains bucket_name (and its source) and target's meaning plus the default-omission behavior. Both parameters are adequately documented, compensating 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?

States a specific resource (one bucket's full config) and enumerates the config sections returned (policy, versioning, lifecycle, encryption, quota, tags), which distinguishes it as the aggregate view versus the sibling subset getters. However, it never names those siblings (bucket_policy_get, bucket_quota_get, etc.) to make the differentiation explicit.

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

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

The parenthetical '(from bucket_ls)' gives a prerequisite cue for sourcing bucket_name, implying a workflow. But there is no explicit guidance on when to use this aggregate tool versus the narrower getters, and no exclusions or conditions are 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?

The annotations already declare readOnlyHint=true, so safety is covered. The description adds meaningful context beyond annotations: it clarifies that null is returned when no lifecycle is set, which is important for result interpretation. It does not disclose error behavior, permissions, or output format, keeping it from a 5.

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

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

The description is front-loaded with the purpose and null-return note, followed by a concise Args block. It is appropriately sized with no wasted sentences, though the bracketed marker and parenthetical slightly add overhead without much information.

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

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

For a two-parameter read tool with a single annotation and no output schema, the description covers purpose, return semantics, and parameter meaning. The main gap is the lack of guidance on alternatives or broader behavior, but nothing critical to correct invocation is missing.

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

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

Schema coverage is 0%, so the description must carry parameter meaning. The Args block explains that bucket_name comes from bucket_ls and that target is the MinIO target name from config, to be omitted for default. This meaningfully compensates for the empty schema descriptions and clarifies the target's purpose and 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?

States a specific verb+resource: retrieves the bucket's lifecycle rules. The clarification '(null when no lifecycle is set)' makes the return semantics unambiguous and distinguishes it from siblings like set_lifecycle, delete_lifecycle, and bucket_policy_get.

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

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

The '[READ]' marker and 'from bucket_ls' hint imply a read-only inspection action, giving some context. However, there is no explicit guidance on when to use this vs lifecycle_gap_analysis, bucket_info, or other read tools, leaving the agent to infer.

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

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

Annotations already declare readOnlyHint=true (echoed by the '[READ][risk=low]' tag, which is redundant). The description adds genuine behavioral value by explaining the two ambiguous return states and the consequence of each (lock never enabled/unable to enable vs WORM available with no default retention), which annotations do not convey.

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

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

Front-loads the tag and purpose before the detail, then cleanly separates the WORM distinction from the Args block. The retention explanation is slightly dense but every clause carries meaning, so nothing is wasted.

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

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

For a two-parameter read with no output schema, the description does the important work of interpreting the returned lock fields (objectLockEnabled, defaultRetention) rather than just naming them. It is nearly sufficient, though it omits what happens for buckets with no lock configuration at all.

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 for both params: bucket_name is sourced from bucket_ls, and target is identified as a MinIO target name with the default-omission behavior spelled out. Minor gaps remain (no format for target, no note on error when the bucket lacks lock config), keeping it below 5.

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

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

States a specific verb+resource with scope: the object-lock (WORM) state of a single bucket. However, it never differentiates itself from the very similar sibling object_lock_status or diagnose_retention_gaps, so an agent cannot easily tell which lock-inspection tool to pick.

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

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

There is no explicit when-to-use guidance and no comparison to alternatives such as object_lock_status. The only routing hint is provenance for one argument ('bucket_name: from bucket_ls'), which is parameter help rather than usage guidance.

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

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

readOnlyHint=true already covers the safety profile, and the description adds genuinely new behavior: the exact return envelope keys (buckets/returned/limit/truncated) and the consequence of truncated being true. Missing only pagination/ordering or auth notes, which are minor here.

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

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

Front-loaded with the [READ] tag and resource, then the return shape, then args. Every sentence earns its place; only the inline envelope example borders on restating what a schema would say, which is acceptable given no output schema exists.

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

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

No output schema exists, so the description correctly supplies the return shape and truncation semantics itself. Both parameters are explained and the read-only nature is consistent with annotations, leaving little an agent needs that is missing.

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

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

Schema description coverage is 0%, so the description must carry the params — and it does: limit is documented as max buckets with a default of 500, and target as a MinIO target name from config where omission means the default. That is meaningful syntax and semantics 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 resource and scope: buckets, with the returned fields named (name + creation time), and flags itself as a [READ] operation. It is clearly distinguishable from object_ls and bucket_info by resource, though it never names a sibling explicitly.

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

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

Usage is implied by the listing nature and the truncation guidance ('re-run with a higher limit rather than reporting the list as complete') gives real operational context. But there is no statement of when to prefer this over bucket_info or how to scope to a specific bucket, so routing guidance is absent.

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

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

Annotations already declare readOnlyHint=true, so the '[READ]' prefix is largely redundant. The description does add value by disclosing the return content (raw policy JSON verbatim plus an anonymous-access summary), which tells the agent what it will actually receive. No mention of auth requirements or what happens when no policy exists.

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

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

Front-loaded with the operation and its return shape, then a compact Args block. The Args entries are somewhat duplicative of the schema but earn their place by adding provenance and default behavior for target.

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

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

No output schema exists, and the description covers the return value (verbatim policy JSON + anonymous-access summary), so the agent knows what to expect. For a two-parameter read tool this is close to complete; only edge behavior (no policy set, permission errors) is absent.

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

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

Schema description coverage is 0%, so the description carries the parameter burden — and it does: bucket_name provenance (from bucket_ls) and target semantics (MinIO config target, omit for default) are both documented. That is meaningful compensation beyond the bare schema types.

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

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

Specific verb+resource: reads the bucket's policy JSON (verbatim) plus an anonymous-access summary. '[READ]' immediately establishes the operation class. It does not explicitly name which sibling to prefer (e.g., bucket_info or bucket_exposure_audit), so it stops short of full 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?

Usage is implied by the name and the '[READ]' tag, and it helpfully notes that bucket_name comes from bucket_ls, which is a real workflow hint. However, it never states when to use this versus bucket_info, bucket_exposure_audit, or bucket_lock_config. No exclusions or prerequisites are given.

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

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

Annotations only declare readOnlyHint=true, and the description adds genuinely new behavioral context: admin credentials are required, and a returned value of 0 means unlimited. It stops short of describing behavior when no quota is set or what happens on auth failure.

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

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

Two tight lines plus an args list; the read tag, the core fact, and the prerequisite are front-loaded, and every sentence carries information the agent needs.

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, two-parameter tool with no output schema, the description covers purpose, auth prerequisite, parameter sourcing, and the meaning of the returned value. Minor gaps remain around error/empty-quota behavior, but nothing essential to calling it is missing.

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

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

Schema description coverage is 0%, so the description carries the full burden, and it does: bucket_name is sourced from bucket_ls, and target is a MinIO target name from config that defaults when omitted. Both parameters are explained, though neither is given format or validation detail.

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

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

States a specific verb+resource: it reads the bucket's hard quota, and the '[READ]' tag plus the '(0 = unlimited)' clarification make the operation unambiguous. It does not explicitly name its write counterpart set_bucket_quota, so the sibling differentiation is only implied by the read tag.

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

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

The '[READ]' marker and the admin-credential prerequisite imply when this tool applies, and the target note ('omit for the default') guides invocation. However, it never states when to prefer this over siblings such as bucket_info or set_bucket_quota, leaving the read-vs-write routing to inference.

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

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

The readOnlyHint annotation already establishes safety, and the description is consistent with it via the '[READ]' tag. Beyond that, it discloses the domain of return values (Enabled / Suspended / Off), which is genuinely useful information not present in structured fields since there is no output schema.

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

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

Two tight components: a one-line purpose with the return-value domain front-loaded, followed by a short Args block. Every sentence earns its place and nothing is padded.

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

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

For a simple two-parameter read tool with no output schema, the definition covers what it reads, the possible results, and both parameters including the default-omission behavior. Nothing an agent needs in order to call it correctly is missing.

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

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

Schema coverage is 0% — the JSON schema carries no descriptions at all — so the description must carry the full burden, and it does: bucket_name is tied to its source tool (bucket_ls) and target is explained as a MinIO target name from config, with the omission behavior for the default explicitly stated.

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+resource — reading a bucket's versioning state — and enumerates the possible states (Enabled/Suspended/Off), so the agent knows exactly what question this tool answers. It does not explicitly name the mutating counterpart set_versioning to differentiate, so it falls just short of a 5.

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

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

The '[READ]' tag and the phrase 'The bucket's versioning state' imply this is the non-mutating way to inspect versioning, which implicitly distinguishes it from set_versioning in the sibling list. However, no explicit when-to-use, prerequisite, or alternative is given (e.g., 'use before calling set_versioning' or 'not to be confused with bucket_info').

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

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

The readOnlyHint annotation already covers the safety profile, and the description reinforces it with a "[READ]" prefix. It adds real behavioral context beyond the annotation by disclosing the output shape (ranked findings, each with cause and suggested action) even though no output schema exists.

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

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

Four tight sentences: purpose, when-to-call, what-it-aggregates, and the one argument. Front-loaded with the primary use case and 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?

With one optional parameter and no output schema, the description supplies the missing return-value information (cause + suggested action per ranked finding) and the parameter's source/omission behavior. Nothing an agent needs to call it correctly is absent.

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

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

Schema coverage is 0%, so the description carries the full burden for the single parameter, and it does: "MinIO target name from config; omit for the default." That supplies both the value source and the omission semantics, matching the schema's null default.

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

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

States a specific verb+resource (capacity & usage RCA) and enumerates exactly what it folds together: capacity vs used, offline drives/nodes, per-drive hotspots, imbalance. That scope clearly separates it from point-read siblings like usage_by_bucket, drive_status, and cluster_status.

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

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

"Call this first on any 'storage is filling up / writes are failing' question" gives an explicit trigger condition and an ordering rule relative to siblings. It stops short of naming which sibling to fall back on for narrower questions, so it is clear context rather than full when/when-not routing.

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

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

Annotations already declare destructive and non-idempotent, but the description goes well beyond them: reversibility to the prior rule, the fact that object lock stays enabled (S3 has no disabling call), that existing retained objects are unaffected, and that future uploads become unprotected. This is exactly the side-effect disclosure a mutation tool needs.

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

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

Front-loaded with a risk tag and one-line purpose, followed by precise caveats, then a compact Args block. Every sentence adds distinct information; nothing is padded or repeated.

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

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

For a destructive, no-output-schema tool, the description covers reversibility, scope limits, and side effects, so an agent knows exactly what will and won't change. Nothing material is missing.

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

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

Schema coverage is 0%, so the description carries the full burden, and it does: bucket_name with a precondition (object lock enabled), dry_run with semantics (preview without clearing), and target with its config source and default-omission behavior. Minor gap: no format details for target/bucket_name.

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

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

States a specific verb (clear/remove) and resource (DEFAULT retention rule), explicitly scoped to the rule rather than the bucket's lock config. An agent can distinguish it from set_default_retention and set_object_retention without opening a schema.

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

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

The description clarifies the narrow scope ('clears the rule only') and implies when it applies versus object-level retention operations (objects already carrying retention keep it). It lacks an explicit named alternative or when-not condition, but the effect-based framing gives 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?

readOnlyHint=true already declares the safe-read profile, so the '[READ]' tag adds nothing new. The description does add value by listing the data categories returned (nodes, drives, capacity, buckets, objects), which helps an agent judge the payload, but it says nothing about freshness, pagination, or failure behavior on an unreachable target.

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

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

Very short and front-loaded: purpose first, then the single arg with its default. No filler sentences. The redundant '[READ]' prefix is the only wasted token, and it is minor.

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 annotated read with one optional param and no output schema, the description covers purpose and the parameter, but leaves the agent guessing how this overlaps with fleet_overview, server_info, node_status, and drive_status, and gives no sense of the return shape despite aggregating five distinct categories.

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 for the single 'target' parameter, and it does: it explains the value is a MinIO target name drawn from config and that omission selects the default. That is meaningful beyond the bare string/null schema, though it gives no naming/format example.

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

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

States a specific resource and enumerates exactly what is summarized (nodes, drives, capacity, buckets, objects), so an agent can tell it is an aggregate dashboard read rather than a per-entity query. However, it does not differentiate itself from close siblings like fleet_overview, server_info, or node_status, which also report cluster-level state.

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

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

There is no when-to-use guidance, no prerequisites, and no named alternative among the many sibling status/overview tools. The only instruction is about the target parameter's default, which is parameter semantics, not usage routing.

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

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

Adds substantial behavior beyond the annotations: the secret is redacted from the audit row and never returned (with rationale about verbatim result storage), a new user has no policy by default, and critically MinIO treats this as an upsert that REPLACES an existing secret with no undo for the old value. This goes well past destructiveHint=true/idempotentHint=false.

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

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

Front-loaded with the [WRITE][risk=medium] tag and a one-line purpose, then scoped rationale and args. Mostly efficient, though the redaction rationale sentence ('the harness stores a result verbatim...') is slightly verbose for the point it makes.

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

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

For a mutation tool with no output schema and 0% param coverage, the description covers operation type, upsert/no-undo semantics, secret handling, default-policy state, and every parameter. An agent has everything needed to invoke it correctly.

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

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

With 0% schema description coverage, the Args block fully compensates: it documents all four parameters including constraints the schema lacks (access_key 3-128 chars with allowed character class, secret_key 8+ chars, dry_run preview semantics, and target name/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?

States a specific verb+resource ('Create or reset an IAM user') and immediately flags it as a write operation with risk level. This is clearly distinct from sibling tools like remove_user, set_user_status, and attach_user_policy.

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

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

Gives clear context: 'Reversible → remove' points at the undo/removal path, and the note that a new user 'can do nothing until one is attached' implies the follow-up with attach_user_policy. It does not name an explicit alternative or exclusion (e.g. 'to disable instead, use set_user_status'), so no full 5.

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

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

Annotations only give destructiveHint=true and idempotentHint=false; the description goes further by disclosing the risk level (medium), the post-state (private/default), and a genuine undo path ('prior policy JSON is captured and re-applied on undo'). This is meaningful behavioral context beyond the annotations.

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

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

Front-loads the [WRITE][risk=medium] tag and purpose, then reversibility, then args – every line is useful. The bracketed tagging and indented arg block are slightly busy but earn their place.

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

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

For a mutation tool with annotations covering the safety profile and no output schema, the description supplies the missing pieces: risk level, reversibility, post-state, and all three undocumented params. Nothing critical to a correct call is absent.

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

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

Schema coverage is 0%, so the description carries the full burden, and it documents all three params: bucket_name with a source hint ('from bucket_ls'), dry_run semantics, and target defaulting behavior. It compensates well, though format details (e.g. target naming) are still thin.

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

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

States a specific verb+resource ('Remove the bucket policy') and names the resulting state ('back to private/default'), which lets an agent distinguish it from set_bucket_policy and bucket_policy_get without opening any schema.

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

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

The purpose implies when to use it (clearing a policy), and it explains dry_run as a preview path, but it never names alternatives such as set_bucket_policy or states when-not to use it. Usage is implied rather than routed.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds genuine context beyond them: the [WRITE][risk=medium] tag and especially 'Reversible → prior config', which tells the agent the operation can be undone. The dry_run preview option is also disclosed. Only a small gap remains (no auth/permission requirements).

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

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

Front-loaded with the write/risk tags and the action, followed by a compact Args block. Every line earns its place; 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 destructive mutation with annotations present and no output schema, the description covers reversibility, risk level, dry-run preview, and all parameters. It is nearly complete, missing only permission/auth requirements.

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: bucket_name includes a provenance hint ('from bucket_ls'), dry_run explains the preview behavior, and target explains the default-omission semantics. All three params are covered with 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?

States a specific verb and resource with scope ('Remove all lifecycle rules'), which cleanly distinguishes it from set_lifecycle and bucket_lifecycle_get. It does not explicitly name an alternative sibling, so it stops short of a 5.

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

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

There is no explicit when-to-use, when-not-to-use, or alternative routing guidance. The dry_run mention hints at a preview workflow, but the description never contrasts this with set_lifecycle or explains when deletion is appropriate.

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

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

Annotations declare readOnly=false, destructive=true, idempotent=false, and the description adds context well past that: the risk level, that the operation is reversible via attach, the dry_run preview semantics, and a genuine safety guard explaining the operation is refused for the tool's own credential because the account would lose the rights needed to undo. This is exactly the behavioral context annotations cannot carry.

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

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

Front-loaded with the WRITE/risk tag, followed by the reversibility and refusal notes, then a clean Args block - the ordering is sensible. The refusal sentence is dense and slightly awkward, but it earns its place as a safety disclosure 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 destructive IAM mutation with no output schema, the definition covers invocation parameters, safety guard, reversibility, and dry-run behavior. Return-value explanation isn't required here, so the only minor gap is the lack of explicit failure/permission conditions beyond the self-credential refusal.

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

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

Schema coverage is 0%, so the description carries the full parameter burden, and it documents all four: access_key, policies, dry_run (preview without detaching), and target (omit for the default). Naming iam_users as the origin of access_key/policies adds value beyond the bare schema types, though format examples (e.g. policy name syntax) are absent.

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 (detach) and resource (canned policies from a user), with a [WRITE][risk=medium] tag that immediately frames the operation. The inverse sibling attach_user_policy is named via 'Reversible → attach', so an agent can distinguish it from its counterpart without opening either schema.

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

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

The reversibility note routes the agent to attach_user_policy as the undo path, and the Args section points access_key and policies at iam_users as their source. However, it does not give explicit when-to-use wording or exclusions beyond the reversal relationship.

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

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

Annotations only declare readOnlyHint=true, and the description adds real context: the [READ][risk=low] tag, the group-policy resolution behavior, worst-first ranking, and the critical disclosure that MinIO denies by default so NO_EFFECTIVE_POLICY accounts are silently broken. It stops short of describing envelope shape or cost, but the behavioral value added is substantial.

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

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

Front-loaded with the read/risk tag and one-line summary, then the substantive detail. The finding list is dense but each category earns its place by telling the agent what can be returned. Slightly verbose in the parenthetical explanation, but no wasted sentences.

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

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

For a two-parameter read-only diagnostic with no output schema, the description covers purpose, ranking semantics, finding taxonomy, and both parameters. An agent has enough to call it correctly; only the envelope structure and pagination details are unstated.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning, and it does: limit is the maximum findings returned and truncation is reported in the envelope, while target is the MinIO target name from config with an explicit omit-for-default rule. Both of the two parameters are explained beyond their bare titles.

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

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

States a specific verb+resource (diagnose IAM exposure) and enumerates the concrete finding categories returned (NO_EFFECTIVE_POLICY, FULL_ADMIN_POLICY, BROAD_DATA_POLICY, DISABLED_BUT_PRIVILEGED). This clearly distinguishes it from sibling listing tools like iam_users and iam_policies, which enumerate rather than diagnose.

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 its value proposition (it resolves group-inherited policies so correctly-managed users aren't misreported), which hints at when it beats a raw user listing. However, it never explicitly states when to choose this over iam_users, iam_policies, or bucket_exposure_audit, nor does it state exclusions. Usage is implied, not prescribed.

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

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

Annotations only declare readOnlyHint=true, so the description carries the rest and does add real context: failing buckets surface in bucketErrors rather than being silently dropped, and the envelope reports truncation when limit is hit. It does not describe cost, per-bucket probe behavior, or rate/size constraints, keeping it below 5.

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

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

Front-loaded with the read/risk tag and a one-line purpose, followed by dense but relevant detail on finding types and error handling. The prose is slightly embellished ('the capacity never returns', 'rather than a house style') but each sentence conveys selection-relevant behavior, so little is wasted.

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

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

No output schema exists, and the description compensates by naming the finding categories, the bucketErrors envelope field, and the truncation signal. For a two-param read-only diagnostic, the agent has everything needed to call it and interpret the result.

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

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

Schema description coverage is 0%, so the description must compensate, and the Args block documents both parameters: limit is the max findings (with truncation signal in the envelope) and target is a MinIO config name with omission meaning default. This is meaningful beyond the raw schema, though it stops short of describing the limit's default behavior or range.

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

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

States a specific verb+resource: diagnosing WORM/retention gaps across every bucket, returned worst-first. It even enumerates the exact contradiction classes it finds (lock with no default retention, lifecycle expiry vs. retention, object lock without versioning), which makes the scope unambiguous. It does not explicitly differentiate itself from the very similar sibling lifecycle_gap_analysis, so it stops short of a 5.

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

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

The '[READ][risk=low]' tag and 'worst-first' ordering imply an audit/diagnostic use case, and the note about bucketErrors implies it is a sweep rather than a single-bucket check. However, there is no explicit when-to-use vs. when-not statement and no pointer to alternatives such as lifecycle_gap_analysis or bucket_exposure_audit.

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

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

With only readOnlyHint=true from annotations, the description carries the rest and does so well: it discloses the exact return shape, the sort order, and a critical interpretation rule that a non-null 'error' means the metrics scrape failed rather than a healthy empty fleet. That last point is exactly the kind of failure-mode context an agent cannot get from structured fields.

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

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

Front-loaded purpose sentence, then return contract, then the caveat, then args - a sensible ordering with little waste. The '[READ]' prefix is slightly redundant against readOnlyHint=true, but it is a single token and the rest of the text earns its place.

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

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

There is no output schema and only one annotation, so the description must explain returns - and it does, down to the keys and the error semantics. Combined with the parameter definition, an agent has everything needed to call and interpret this tool.

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

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

Schema description coverage is 0% for the single 'target' parameter, so the description must compensate and it does: it defines target as the MinIO target name from config and states the omit-for-default behavior. That is complete semantic coverage for a one-parameter tool.

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

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

States a specific resource and scope: per-drive rows with the fields returned (server, drive, used ratio) and the ordering (fullest first). This implicitly separates it from node_status, cluster_status and fleet_overview, which operate at coarser granularity. It does not name those siblings explicitly, so it falls short of a 5.

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

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

Usage is implied by the 'fullest first' ordering and the warning about interpreting an empty list, which tells the agent the intended use case is capacity checking. However, no alternative tool is named and there is no when-not guidance, even though capacity_rca and usage_by_bucket are plausible substitutes for capacity questions.

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

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

The readOnlyHint annotation already declares the safety profile, and the [READ] tag and 'one-shot ... headline' wording add useful context that this is an aggregated read rather than a raw detail dump. However, it doesn't describe pagination, freshness, or whether the sections can be individually expanded, so it adds only modest value beyond the annotation.

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

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

Two front-loaded sentences plus a compact Args block; no waste. The lead sentence names the operation and its three coverage areas before the usage instruction.

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

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

For a single-parameter, read-only, no-output-schema tool, the description covers purpose, trigger, and the parameter's meaning. The only minor gap is that the shape/format of the returned 'headline' sections is not characterized.

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

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

Schema description coverage is 0%, so the description carries the burden for the single parameter. It does so fully: 'target: MinIO target name from config; omit for the default,' explaining both the source of valid values and the default-omission 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?

States a specific verb and composite resource: a 'one-shot deployment overview' covering health, capacity, and exposure. The 'call this first' framing implicitly differentiates it from the many granular siblings (health_live, capacity_rca, bucket_exposure_audit), though it doesn't name any of them directly.

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

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

Gives an explicit trigger condition: 'Call this first on any broad "how is my object storage doing" question.' It provides clear entry-point context but does not state when to skip it in favor of the narrower 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?

The [READ] tag and readOnlyHint align, and the description adds real context beyond the annotation: it enumerates what is computed (per-erasure-set online drives vs write quorum, remaining failure tolerance, drives healing, heal backlog/errors) and states output is delivered as plain-language findings. It does not cover auth requirements or rate limits, but for a read-only diagnostic that is acceptable.

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

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

Front-loads the READ marker and the tool's outputs, then the framing question, then the argument. Every sentence is substantive; only slight redundancy between the opening line and the list of signals.

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

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

With no output schema, the description must convey return content, and it does so by listing the specific findings produced. Combined with the parameter explanation, an agent has enough to invoke and interpret it, though the exact finding format is only loosely described.

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

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

Schema coverage is 0%, so the description must carry the parameter burden, and it does: 'target: MinIO target name from config; omit for the default' explains meaning and default behavior. This fully compensates for the single undocumented parameter.

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

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

States a specific resource (healing backlog + erasure-set write-quorum risk) with a clear framing question, so the agent knows this tool reports failure-tolerance diagnostics. It is highly distinctive versus siblings like drive_status or health_cluster, though it does not explicitly name which sibling to prefer.

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

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

Usage is implied by the framing question ('how many more drive failures can I take?'), which scopes the scenario well. However, there is no explicit when-to-use/when-not guidance and no named alternative among the many health/diagnostic siblings (drive_status, cluster_status, health_cluster).

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

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

Annotations only declare readOnlyHint=true; the description adds real behavioral context beyond that: the HTTP endpoint probed, the meaning of a 503 response, and that the result is a single structured answer with an aggregate 'healthy' verdict. It does not cover error/auth behavior, but the read-only safety profile is already covered by 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 purpose and status-code semantics are front-loaded in the first line, and the parameter note is compact. The multi-line layout adds minor visual noise but no filler sentences.

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

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

With no output schema, the description usefully sketches the return shape (combined liveness/readiness plus an overall 'healthy' verdict) and gives the failure signal (503=degraded). For a zero-required-param read probe this is nearly complete; only error/auth conditions are unaddressed.

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

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

Schema description coverage is 0% for the single 'target' parameter, so the description carries the burden and does so: 'MinIO target name from config; omit for the default.' That explains both the value source and the omission/default behavior, which the bare anyOf[string,null] schema does not.

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

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

The description names a specific verb+resource ('Cluster write-quorum health'), gives the underlying endpoint, and explains the 503=degraded signal. It also implicitly distinguishes itself from the health_live/health_ready siblings by noting it folds liveness and readiness into one structured answer, though that differentiation is phrased loosely rather than as an explicit contrast.

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

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

The '[READ]' tag and 503 semantics imply it is a diagnostic probe, and the mention of liveness/readiness suggests it can substitute for those sibling calls. However, there is no explicit when-to-use/when-not guidance relative to health_live, health_ready, cluster_status, or healing_health, leaving selection to inference.

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

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

Beyond readOnlyHint=true, it discloses two meaningful behavioral facts: the probe requires no authentication and hits a specific fixed path. It does not describe failure modes, timeout behavior, or what a negative result looks like.

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

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

Front-loaded with the [READ] marker and the core action, then a short args block. Two short lines, no filler, though the inline 'Args:' formatting adds mild noise for a one-parameter tool.

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

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

The lowest-cost call in the set and no output schema exists, yet the description never says what the probe returns (e.g., liveness success/failure shape). Nothing else an agent needs is missing, but the return semantics gap keeps this at minimum-viable rather than complete.

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

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

Schema coverage is 0%, so the description must carry the single parameter, and it does: 'target: MinIO target name from config; omit for the default' explains origin and the omit-for-default behavior that the bare schema cannot. It could add acceptable value formats but the essential meaning is covered.

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

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

States a specific verb+resource ('Node liveness probe') and pins it to a concrete endpoint (/minio/health/live), which clearly separates it from transactional siblings. It does not explicitly contrast itself with the nearby health_ready/health_cluster tools, so an agent must infer the liveness-vs-readiness distinction.

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 (a liveness check you call without credentials) and tells the caller how to pick a target, but never states when to prefer this over health_ready, health_cluster, or node_status. Only implied guidance is present.

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

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

Annotations only declare readOnlyHint=true; the description adds that the probe is unauthenticated and hits a specific HTTP path, which is genuinely new behavioral context an agent cannot get from the annotations. It still doesn't say what a failure looks like (error vs. non-ready status) or what the response body contains.

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

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

Front-loaded with the '[READ]' tag and the core purpose, then a single Args line covering the one parameter. No filler or redundancy; every element earns its place.

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

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

For a zero-required-parameter, no-output-schema health probe with readOnlyHint already set, the description gives enough to invoke correctly, including auth expectations and the endpoint. The only gap is the absence of any hint about the return shape or how 'not ready' is surfaced.

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 param burden, and it does: 'target' is a MinIO target name sourced from config, and omitting it selects the default. That fully explains the single parameter's semantics and default behavior, though it doesn't clarify what happens with an unknown target name.

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

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

States a specific verb+resource ('Node readiness probe') and even names the underlying endpoint (/minio/health/ready), which pins down exactly what is checked. It does not explicitly contrast itself with the sibling health_live / health_cluster probes, so the readiness-vs-liveness distinction is left to the reader's inference.

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

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

The '[READ]' tag and the word 'probe' imply this is a passive diagnostic to call when checking node health, but there is no explicit when-to-use statement and no guidance on choosing it over health_live, health_cluster, node_status, or drive_status. Usage is implied rather than stated.

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

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

Consistent with readOnlyHint=true and adds genuine behavioral detail beyond the annotation: per-group read failures surface in groupErrors instead of being dropped, and truncation is reported by the envelope. It does not cover auth/permission requirements, but for a read tool this is solid disclosure.

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

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

Front-loaded with the risk/read tag and the resource, then a short note on failure handling, then a compact Args block. Every sentence earns its place; only the Args formatting is slightly boilerplate.

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

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

No output schema exists, yet the description explains the notable return behaviors (groupErrors, truncation reporting), which is what an agent most needs to interpret results. The remaining gap is permission/auth context for IAM reads.

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

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

Schema description coverage is 0%, so the description carries the full burden and does so: limit is defined as a cap with truncation reported in the envelope, and target is defined as a MinIO target name from config with omission meaning the default. Both parameters gain meaning not present in the schema.

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

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

States a specific resource (IAM groups) and scope (members and attached policies), which distinguishes it from siblings iam_users and iam_policies. The verb is implied via the [READ] tag rather than stated, so it is clear but slightly less explicit than a 5.

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

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

The [READ][risk=low] tag implies a safe read operation, and the content description implies when it is useful (enumerating groups with their memberships and policies). However, no alternative is named and no when/when-not guidance is given, leaving routing to inference.

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

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

Annotations already carry readOnlyHint, so the bar is lower, yet the description adds real context: the risk label, the truncation-reporting behavior of the envelope, and the target defaulting semantics. These go beyond what the annotations declare.

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

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

Front-loaded with the READ/risk tag, then the purpose, then concise arg notes. No filler, and the args block maps cleanly to the two parameters.

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 list tool with no output schema, the description covers what is returned (policy names), truncation signaling, and target scoping. Adequate 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?

Schema description coverage is 0%, so the description must compensate and largely does: it defines limit (max names to return, with truncation reported) and target (config target name, omit for default). Only minor format/syntax detail is missing.

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

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

The description states what the tool returns - the canned policy names defined on the deployment - and the name/prefix 'iam_policies' plus parallel siblings (iam_users, iam_groups) make the resource distinct. It is clear but does not explicitly distinguish itself from adjacent tools such as diagnose_iam_exposure.

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

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

The '[READ][risk=low]' tag and 'from config; omit for the default' note imply a read-only inventory call, but there is no explicit when-to-use or when-not guidance relative to the other IAM 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?

The [READ][risk=low] tag is consistent with readOnlyHint=true, and the description adds genuinely new behavioral context: empty results are expected on root-only deployments (not a failed probe), and the envelope reports truncation. It does not cover pagination mechanics, but the added edge-case disclosure goes meaningfully beyond the single annotation.

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

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

The risk tag and resource summary are front-loaded, and the Args block is tight with two one-line entries. The empty-list paragraph is slightly verbose for its purpose but earns its place by preventing a false failure diagnosis.

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

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

For a read-only listing tool with no output schema and two optional parameters, the description covers what is returned, both parameters, and the important empty-result caveat. Nothing critical is missing, though it does not say whether the list is paginated or how nested policy/group data is shaped.

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

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

Schema description coverage is 0%, so the description must carry the parameter burden, and it does: 'limit' is tied to truncation reporting and 'target' is tied to a config-named MinIO target with an explicit default-omit rule. Both parameters gain semantics absent from the schema, though no default value or type detail is restated.

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

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

The description names the resource (IAM users) and the payload fields returned — status, attached policies, group membership — so an agent knows this is a read of IAM user state. It never states a verb explicitly and does not distinguish itself from near siblings like iam_groups, iam_policies, or create_user/remove_user, but the resource is 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?

There is no explicit when-to-use guidance and no routing to alternatives such as iam_groups or iam_policies. The root-credential note explains how to interpret an empty result, which is useful context but is correctness guidance, not selection guidance.

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

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

readOnlyHint=true already declares the safety profile, and the description adds real behavioral context beyond it: the truncation-aware envelope, the exact return keys, the null-initiated-time edge case, and the re-run-on-truncation remedy. With no output schema present, this return-shape disclosure is valuable rather than redundant.

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

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

Front-loads the [READ] tag and purpose, then the return envelope, then a compact Args block. Every line earns its place with no filler, and the pagination remedy is placed where it is needed.

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-param, read-only listing tool with no output schema, the description covers purpose, return format, edge cases, and all parameters. Combined with the readOnlyHint annotation, an agent has everything required to call it correctly.

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

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

Schema coverage is 0%, so the description carries the full parameter burden and does so completely: it explains bucket_name (pointing to bucket_ls as its source), prefix semantics ('empty for the whole bucket'), limit with its default, and target with the 'omit for the default' rule. This adds meaning well beyond the bare schema titles.

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

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

States a specific verb+resource ('in-flight/abandoned multipart uploads') with a [READ] scope tag, so the agent knows it lists rather than deletes. It does not, however, differentiate from the sibling remove_incomplete_uploads (its write counterpart) or object_ls, so sibling disambiguation is left to inference.

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

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

It gives one actionable operational rule ('When truncated is true, re-run with a higher limit'), which is genuinely useful. But it offers no when-to-use/when-not guidance relative to alternatives like remove_incomplete_uploads or object_ls, so the usage context is only implied.

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

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

readOnlyHint=true already covers the safety profile and the '[READ]' tag is consistent, so no contradiction. The description adds real context by naming the gap classes it surfaces and the reclaimable/cause/action shape, but says nothing about scan cost, breadth, or what 'large buckets' thresholds apply.

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

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

Front-loaded with the core read purpose, then a compact enumeration of gap types, then Args. Only mild redundancy in the parenthetical flavor ('old bytes accrue forever', 'invisible space'), but overall tight and well-structured.

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

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

With no output schema, the description carries the return-value burden and characterizes outputs conceptually (gaps, reclaimable estimate, cause + action). For a 2-param read-only diagnostic that is largely sufficient, though output structure and the meaning of 'large' remain underspecified.

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

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

Schema coverage is 0%, so the description must compensate and largely does: it defines limit as 'maximum buckets to analyze' and target as the 'MinIO target name from config; omit for the default,' adding meaning beyond the bare titles and defaults. It does not explain how limit interacts with the result or what happens when it is exceeded.

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

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

States a specific verb+resource ('ILM gaps per bucket + reclaimable estimate, cause + action') and enumerates the three exact gap classes it detects (unversioned-expiry buckets, incomplete multipart uploads, large buckets with no lifecycle). This lets an agent separate it from sibling reads like bucket_lifecycle_get (config read) or diagnose_retention_gaps without opening a schema.

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

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

The enumerated gap categories imply when the tool is useful (auditing remediation opportunities), but it never states when to prefer it over siblings such as bucket_lifecycle_get, diagnose_retention_gaps, or incomplete_uploads_ls, and gives no exclusions or prerequisites. Usage is inferable but not directed.

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

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

Annotations already declare readOnlyHint=true and the '[READ]' tag echoes it, so safety is covered. The description adds value by disclosing what it returns (online/offline node list plus per-node drive counts), which is not in any structured field. No output schema exists, but the one-line return summary is a reasonable, if thin, substitute.

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

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

Front-loaded with the read tag and the core output summary in one sentence, followed by a compact Args block. No filler; every line earns its place.

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

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

For a single-optional-param read-only status tool with annotations covering safety and no output schema, the definition covers purpose, return content, and param behavior adequately. It only lacks sibling disambiguation, which is minor given its narrow scope.

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 schema offers nothing about 'target'. The description compensates by explaining it is a 'MinIO target name from config' and that omitting it selects the default, which is exactly the semantics needed. This meaningfully exceeds what the bare anyOf/null schema conveys.

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

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

The description states a specific verb/resource: a 'node-level view' returning 'online/offline nodes + per-node drive counts.' The 'node-level' framing does distinguish it implicitly from drive_status (drive-level) and cluster_status/fleet_overview (cluster-level), though it doesn't name them. Clear but not explicitly differentiated from the crowded status-tool family.

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

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

No guidance on when to choose node_status versus drive_status, cluster_status, server_info, or the health_* tools. The only conditional text ('omit for the default') addresses the parameter, not tool selection. An agent gets no routing help among ~45 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?

Annotations already declare readOnlyHint=true, so safety is covered; the description goes further by tagging it [READ][risk=low] and explaining the non-obvious stacking semantics of retention vs legal hold. It also says what the call answers (deletable now, what blocks it), which is real behavioral context beyond structured fields.

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

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

Front-loaded with a purpose line, then the deletability answer, then the stacking caveat, then a compact Args block. Every element earns its place; the stacking paragraph is slightly long but is the kind of nuance an agent cannot infer.

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

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

For a read-only status tool with four parameters and no output schema, the description covers inputs, semantics, and the central result (deletable or not, and blocking factors). It stops short of describing the remaining return fields (retention mode/expiry, hold state), which would fully close the gap given no 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?

Schema description coverage is 0%, so the description carries the full burden and largely meets it: it explains bucket_name/object_name sources, that version_id defaults to the current version, and that target defaults to the configured target. This meaningfully compensates for the undocumented schema.

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

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

States a specific verb+resource: reports retention/legal-hold state for one object version and whether it is deletable. This clearly separates it from the sibling setters (set_object_retention, set_legal_hold) and from the bucket-level bucket_lock_config, so an agent can route without opening schemas.

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

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

Implicitly positions itself as the read counterpart to set_object_retention/set_legal_hold and tells the agent where to get inputs (bucket_ls, bucket_objects), but never gives an explicit 'use this when…' or names an alternative such as bucket_lock_config or diagnose_retention_gaps. Usage is inferable rather than stated.

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

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

Annotations already declare readOnlyHint, so safety is covered, and the description adds genuinely non-derivable behavior: the truncation envelope, the 'millions of keys' reality, and that `lastModified`/`versionId` can be null when the source had no value. Missing only minor details like pagination cursor absence or ordering.

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

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

Front-loads the critical truncation warning before the return shape and arg list, so the most important behavioral fact is read first. Slightly verbose with the inline JSON return snippet, but every sentence carries information.

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

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

With no output schema, the description supplies the return envelope shape and null-field caveats, plus per-parameter meaning and the truncation contract. An agent has enough to call it correctly and interpret the result; only deep pagination/ordering semantics are omitted.

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

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

Schema coverage is 0%, so the description carries the full burden and largely does: it documents all four params, giving `bucket_name` origin, `prefix` semantics (empty = whole bucket), `limit` default 100 and max 1000, and `target` as a config name omitted for default. This meaningfully exceeds the bare schema types.

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

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

States a specific verb (list) and resource (objects) plus scope (under `prefix`), and the parenthetical '(never a full walk)' immediately distinguishes it from a bucket-level listing. The 'from bucket_ls' hint ties `bucket_name` to the sibling that produces it, so the boundary against bucket_ls is 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?

Explicitly tells the agent that `truncated: true` is normal and to re-run with a higher limit or narrower prefix rather than treating the page as complete. It gives operational context and remediation but does not name sibling alternatives directly.

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

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

Goes well beyond the destructiveHint=true annotation by disclosing that the parts are unrecoverable, that there is no undo, that priorState records only a count and sample, and that the age threshold shields in-flight uploads. These are exactly the operational facts an agent needs before a destructive call.

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

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

Front-loaded with risk classification, then one tight behavioral paragraph, then a compact args block. Nothing is padded; the args repetition is justified because the schema carries no descriptions.

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

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

For a destructive, non-idempotent tool with no output schema, the description covers safety profile, irreversibility, guardrails, and every parameter. There is no output schema to explain and return behavior (priorState summary) is already noted inline.

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

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

Schema description coverage is 0%, so the description must carry the burden and it does: all four params are documented with meaning beyond the schema, including '0 = all' for older_than_days, the preview semantics of dry_run, and the config-derived target. It also cross-references bucket_ls as the source of bucket names.

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

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

States a specific verb and resource ('Abort abandoned multipart uploads') plus the effect ('reclaims their parts'), which clearly separates it from siblings like incomplete_uploads_ls (which only lists). The '[WRITE][risk=medium]' prefix front-loads the operation class.

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

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

Gives clear conditions for use: only uploads at least older_than_days old are aborted, protecting in-flight uploads, and dry_run previews matches. It stops short of explicitly naming a companion tool (incomplete_uploads_ls) as the pre-check alternative, so it is clear context rather than full when/when-not guidance.

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

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

Annotations already declare destructiveHint=true, but the description goes well beyond them: it states no undo is recorded, that MinIO keeps no recoverable copy of the secret so the account can only be recreated, that priorState captures status and policy for rebuilding rights, and that self-targeting is refused. That is real behavioral depth an agent cannot get from the annotations alone.

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

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

Front-loaded with the [WRITE][risk=high] tag and the irreversibility warning, and the Args block is justified by 0% schema coverage. There is mild redundancy between 'no undo is recorded' and 'keeps no recoverable copy', which keeps it from a perfect score.

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

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

With no output schema, the description helpfully indicates that priorState is returned to rebuild the deleted user's status and policy attachments. Combined with documented parameters, the refusal guard, and the irreversibility notice, an agent has everything needed to call this safely.

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

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

Schema description coverage is 0%, so the description carries the full burden, and it does: access_key is sourced from iam_users, dry_run is explained as running guards plus reporting without deletion, and target is described as the MinIO target name from config with omission meaning the default. All three parameters get meaning the bare schema does not provide.

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

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

States a specific verb and resource ('Delete an IAM user') and immediately tags it as [WRITE][risk=high], which cleanly separates it from read-side IAM siblings like iam_users and from non-destructive mutations like set_user_status. An agent can identify the operation 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?

Gives clear operational context: dry_run runs the guards and reports without deleting, and the tool is refused when it targets its own credential, which tells the agent a precondition to check first. It stops short of naming a non-destructive alternative (e.g., set_user_status) for the case where disable, not delete, is wanted, so it is context-rich but has no explicit exclusions.

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

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

readOnlyHint=true already establishes the safe-read profile, and the description reinforces it with '[READ]' rather than contradicting it. It adds genuine context beyond annotations: an admin-credential requirement and the scope of returned data (mode, servers/pools summary). It does not cover rate limits, pagination, or output shape.

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

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

Very short and front-loaded: the read marker, capability, and credential requirement come first, with the argument detail separated into a compact Args block. The sectioned format costs a few tokens but aids scanning.

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

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

For a zero-required-parameter read tool with annotations covering safety, the essentials are present: what it returns, what auth it needs, and how the one parameter behaves. The remaining gap is not differentiating its output from other cluster/health status siblings, which an agent may need to pick correctly.

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

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

Schema coverage is 0% — the target property has no description at all — so the description's 'MinIO target name from config; omit for the default' is doing real work, explaining both the value source and the null/omit behavior. That fully compensates for the single undocumented parameter.

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

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

States a specific verb and resource: retrieves admin server info covering 'mode, servers/pools summary'. This is clear, though it does not explicitly distinguish itself from closely related siblings like cluster_status, fleet_overview, or node_status, leaving the agent to infer the boundary.

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 only usage signal is the prerequisite 'Needs admin credentials' — useful but not guidance about when to choose this over cluster_status, fleet_overview, health_cluster, or drive_status. No when-not or alternative routing is provided despite a dense sibling cluster.

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

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

Goes well beyond the annotations by disclosing that the prior policy JSON is returned for undo, that an anonymous-Allow policy exposes the bucket, and a non-obvious refusal rule (an explicit Deny on s3:PutBucketPolicy covering the tool's own access key blocks the call, even under dry_run) with the reasoning that an explicit Deny beats every Allow. This is exactly the kind of hidden behavior an agent needs before invoking a risky write.

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

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

Front-loaded with the operation tag and a one-line effect/reversibility statement, then an Args block. The refusal paragraph is longer than typical but each sentence adds non-obvious safety information, so it largely earns its space.

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 mutating, non-idempotent tool with no output schema, the description covers safety, reversibility, side effects on bucket exposure, refusal conditions, and every parameter. An agent has everything needed to call it correctly.

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

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

Schema description coverage is 0%, so the description carries the full burden and does so: bucket_name is sourced ('from bucket_ls'), policy_json is constrained ('must contain Statement'), dry_run is explained as preview-only, and target is tied to config with a default. All four parameters are documented.

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

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

States a specific verb and resource ('Replace the bucket policy') and immediately disambiguates from the read/delete siblings (bucket_policy_get, delete_bucket_policy) by naming the mutation and its reversibility. The [WRITE][risk=medium] tag front-loads the operation class.

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

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

Gives clear operational context: use dry_run to preview, and run bucket_exposure_audit after changing policies because an anonymous-Allow policy makes the bucket public. It does not explicitly contrast with delete_bucket_policy or bucket_lock_config, but the when-to-use conditions are well established.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, idempotentHint=false; the description adds the credential requirement (admin API) and the reversibility note plus a medium risk tag, which annotations alone do not convey. It does not explain the effect of lowering a quota on in-flight writes, so it stops short of full behavioral disclosure.

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

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

Risk/type tags are front-loaded, the core operation is stated in one sentence, and the parameter block is scannable with no filler. Every line conveys information.

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

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

For a mutating tool with no output schema, the description covers prerequisites, reversibility, dry-run, and all four parameters. It omits the operational consequence of a reduced quota (write failures) and any error/response expectations, which is the only meaningful gap.

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

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

Schema description coverage is 0%, so the description must carry the load, and it does: size_bytes explains that 0 clears the quota (beyond the schema's bare 'integer'), target explains the default-when-omitted behavior, dry_run explains preview semantics, and bucket_name points at bucket_ls as the source of valid values.

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

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

States a specific verb and resource ('Set (>0) or clear (0) the bucket hard quota'), and the parenthetical clarifies both directions of the operation. It is unambiguously distinct from the sibling bucket_quota_get (read) and set_bucket_policy (different resource).

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 context an agent needs: admin-capable credentials required, dry_run for previewing, and bucket_name sourced 'from bucket_ls'. It does not explicitly say when to prefer this over set_bucket_policy or when not to use it, but the operational preconditions are 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?

Goes well beyond the destructive/readOnly annotations by disclosing what undo does (restores prior rule), that objects written under the rule keep the retention given, and that COMPLIANCE retention on them can never be shortened. It also documents a pre-condition failure mode (no object lock → refusal even in dry_run), which annotations cannot express.

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

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

Front-loaded with the write/risk tag and the core action, then behavior, then a compact Args list. Given zero schema coverage, every line (including the Args block) earns its place with no redundancy.

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

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

For a high-risk, 6-parameter mutation with no output schema, the description covers the action, side effects, undo semantics, irreversibility caveats, refusal conditions, and every parameter. Nothing needed to invoke it correctly is missing.

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

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

With 0% schema description coverage, the description carries the full burden and delivers: it explains mode's GOVERNANCE vs COMPLIANCE semantics, the days/years mutual exclusivity ("pass exactly one"), dry_run behavior, and target's config origin. This adds genuine meaning the raw schema lacks.

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

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

States a specific verb+resource ("Set the bucket's DEFAULT retention") and scopes it to default (future) retention versus per-object rules. The [WRITE][risk=high] tag and the note that existing objects are untouched make it easily distinguishable from siblings like set_object_retention and clear_default_retention.

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

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

Gives clear context: it applies only to objects written from now on, is reversible to the prior rule, and is refused (even under dry_run) when the bucket lacks object lock. It stops short of explicitly naming sibling alternatives (e.g. set_object_retention for existing objects), so it is strong context rather than a full when/when-not routing.

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

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

Annotations declare a non-read-only, non-idempotent, destructive operation, and the description goes well beyond them: it explains that the change is reversible to the prior hold state, that the hold has no expiry date, that it blocks deletion, and that lifting it does not make an object deletable while retention still runs. That interaction-with-retention caveat is exactly the kind of consequence an agent needs before invoking a destructive 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?

Front-loaded with [WRITE][risk=medium] and the one-line action, followed by a short rationale paragraph and a compact Args block. No sentence is filler — even the WORM/reversibility note earns its place by preventing misuse.

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

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

With no output schema, the description still tells the agent what dry_run returns (the current hold state) and what state the object ends in after a real call. Combined with annotations covering the safety profile and full per-parameter docs, nothing needed to invoke this correctly is missing.

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

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

Schema description coverage is 0%, so the description must carry all six parameters — and it does, documenting bucket_name, object_name, hold_on, version_id (omit for current version), dry_run, and target (config name, omit for default). This fully compensates for the empty schema and adds semantics the types alone cannot convey.

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

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

The description gives a specific verb and resource — toggling a legal hold on/off for a bucket object — and immediately differentiates it from the adjacent retention controls ('the one WORM control that is reversible by design', 'stacks with retention'). An agent can separate this from set_object_retention / set_default_retention without opening any schema.

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

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

It states preconditions ('bucket must have object lock enabled'), the meaning of both hold_on values, and offers dry_run as a read-only preview path, which implicitly routes read-only intent away from this tool. It never names an explicit alternative sibling (e.g. object_lock_status for inspection), so it stops just short of a 5.

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

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

Annotations declare destructive=true and non-idempotent, and the description adds substantial non-obvious context: that the prior config is captured for undo, that undo restores the rule but NOT expired data, and that MinIO drops a multipart-abort-only rule. This is exactly the kind of behavior an agent cannot infer from annotations alone.

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

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

Front-loaded metadata tags ([WRITE][risk=medium]) then the replacement/reversibility warning, then mode guidance, then caveats, then args. Dense but every sentence adds a constraint the agent needs for a destructive write.

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

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

No output schema exists, but the description covers all required behavior for a 7-param destructive mutation: reversibility, undo limits, dry_run, target resolution, and the excluded multipart case. Nothing material is missing.

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

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

Schema description coverage is 0%, so the description carries the full burden and does: each of the 7 args is given semantics (bucket_name sourced from bucket_ls, prefix empty=whole bucket, lifecycle_xml verbatim, target omitted=default, dry_run preview). Nothing is left undocumented.

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

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

Opens with a specific verb+resource ("Replace the bucket lifecycle") and immediately clarifies that it REPLACES existing rules, which cleanly separates it from delete_lifecycle and bucket_lifecycle_get. An agent can identify the operation without opening the schema.

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

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

Explicitly routes between the two modes: day-count knobs for built rules vs lifecycle_xml for verbatim application (noting the undo path uses the latter). It also names a real alternative (remove_incomplete_uploads) and explains why the multipart-abort action is out of scope here.

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?

Extraordinarily rich beyond the annotations: no undo token is recorded, S3 refuses to shorten retention without the bypass-governance-retention header which the SDK never sends, COMPLIANCE cannot be lifted by any credential including root until the date passes, and both refusal paths fire under dry_run. This is exactly the destructive/irreversible context an agent needs.

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

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

Front-loads the critical [WRITE][risk=critical] warning and 'NO UNDO EXISTS' before the mechanics and args. The prose is dense but almost every clause carries decision-relevant information; only mild redundancy between the header warning and the body costs it a 5.

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

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

No output schema exists, yet the description explains what dry_run returns (before-state) and exactly what a refused call does. For a critical, irreversible, 8-parameter mutation tool, 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 description coverage is 0%, so the description carries the full load and does: mode values are explained with their liftability semantics, days is anchored ('from now'), version_id defaults to current, dry_run is defined as running every guard and reporting before-state, bucket_name notes the object-lock prerequisite, and object_name cites its source. All 8 parameters gain meaning.

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

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

States a specific verb and resource: 'Put retention on one object version.' The scope ('one object version') cleanly separates it from set_default_retention, set_legal_hold, and bucket_lock_config. An agent can select it without opening the schema.

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

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

Provides strong conditional guidance: COMPLIANCE requires acknowledge_irreversible=True, shortening/downgrade attempts are refused, and guards still fire under dry_run. It doesn't explicitly compare against sibling tools like set_default_retention or set_legal_hold, so a 4 rather than 5.

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

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

Goes well past annotations: discloses reversibility to prior status, the self-target refusal edge case, and that dry_run does not bypass enforcement. Annotations only say destructive/idempotent hints; the description adds the operational guardrails that actually matter.

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

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

Front-loaded [WRITE][risk] tag, then the critical refusal rule, then Args. Slightly verbose with '(from iam_users)' and the aside about the undo, but every element adds signal.

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

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

No output schema, but the description covers mutation effect, reversibility, preview semantics, and the refusal case. Return shape is only implied by 'Reversible -> prior status', a minor gap for a write tool with no 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?

Schema coverage is 0%, so the description must carry params. It documents all four (access_key, enabled, dry_run, target) with brief meaning, including the default target. Values are terse but sufficient to call 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?

Specific verb+resource ('Enable or disable an IAM user status') with a [WRITE][risk=medium] tag and a Reversibility callout. It clearly distinguishes itself from siblings like iam_users (list) and create_user/remove_user by scoping to status toggling.

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

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

States a strong when-NOT condition: refused when targeting the tool's own access key, enforced even under dry_run. Lacks explicit routing to alternatives (e.g., use remove_user for deletion), but the exclusion guidance is concrete and rare.

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

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

Annotations already declare readOnly=false, destructive=true, idempotent=false, and the description adds genuinely new context: a risk tag ([WRITE][risk=medium]), a reversibility claim ('Reversible → prior state'), and the semantics of dry_run as a preview mode. Note the mild tension between 'Reversible' and destructiveHint=true, but reversibility and destructiveness are not mutually exclusive, so this is added context rather than a contradiction.

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

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

A single front-loaded action line followed by a compact Args list. Given 0% schema coverage the per-parameter lines are load-bearing rather than redundant, and there is 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 4-param write tool with no output schema, the description covers action, safety posture, reversibility, dry_run, and every parameter. It omits the side effects an agent would want on a versioning mutation - what happens to existing object versions when suspended, and any permission prerequisites - which keeps it short of full completeness.

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

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

Schema description coverage is 0%, so the description carries the full burden and does: it documents all four parameters, including an allowed-value set for status ('Enabled' or 'Suspended') that the schema lacks as an enum, the provenance hint for bucket_name ('from bucket_ls'), the target fallback behavior, and dry_run semantics.

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 pair and resource: 'Enable or suspend bucket versioning.' The set/write verb set clearly separates it from read siblings such as bucket_versioning_get, so an agent can tell the tools apart without opening a schema.

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

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

Usage is only implied by the verb and the dry_run parameter. There is no explicit when-to-use, no when-not-to-use, and no routing guidance toward the sibling versioning reader (bucket_versioning_get) or related lifecycle tools; the agent must infer 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?

Annotations declare destructive=true and idempotent=false; the description adds real context beyond them – the inverse is dispatched through its own governed tool and audited under its own risk tier, dry_run previews without executing, and a token can only be applied once. These are material behavioral facts an agent needs.

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

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

Front-loaded with a [WRITE][risk=medium] tag, then purpose, behavioral notes, and a compact Args block. Every sentence earns its place given the 0% schema coverage, though it is slightly verbose in places.

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

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

For a destructive, non-idempotent mutation with no output schema, it covers preview, single-use, and audit routing. The return shape of a dry_run preview is only lightly described, leaving a minor gap, but the essentials for correct invocation 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?

Schema description coverage is 0%, so the description carries the burden and documents all three params: undo_id (its origin), dry_run (preview semantics), and target (pass-through to the inverse tool when accepted). It adds genuine meaning, though it doesn't fully specify types or edge 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?

States a specific verb+resource ('Apply a recorded undo by dispatching its inverse tool') and distinguishes itself from the sibling undo_list by naming it as the source of the undoId. An agent can tell immediately what this does versus merely listing undo tokens.

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

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

Gives clear operating context: obtain the undoId from undo_list (or an `_undo_id` in a write result), pass dry_run=True to preview, and note that a token is single-use. It stops short of explicit when-not-to-use guidance, but the workflow is unambiguous.

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

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

Annotations only supply readOnlyHint=true; the description goes well beyond that by disclosing the return shape, that truncation is *measured* via an extra-row fetch, and that effectVerified=false means the reversed change is only PROBABLE, with a caution to check live state and not over-report. This is meaningful operational context the annotations cannot carry.

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

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

Front-loaded with purpose and the sibling handoff, then structured paragraphs for return value and the effectVerified caveat. Every sentence carries information, though the emphasis on truncation being 'measured, not guessed from a length coincidence' is slightly verbose for the value it adds.

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

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

With no output schema present, the description supplies the return JSON shape, the meaning of every field an agent must act on (returned, limit, truncated, effectVerified), and the follow-up behavior for truncation. Nothing needed to call or interpret it correctly is missing.

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

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

Schema description coverage is 0% and no param has an enum, so the description must compensate, and it does fully: limit is documented as default 50 / capped at 500, and target is documented as ignored with the reason (host-local undo state, kept for CLI uniformity).

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

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

States a specific verb and resource ('List recorded, not-yet-applied undo tokens') plus ordering ('most recent first'). The [READ] tag and the reference to undo_apply make it clearly distinguishable from the sibling that actually applies tokens.

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

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

Explicitly routes the agent: 'Use the undoId with undo_apply.' and tells it to re-run with a higher limit when truncated rather than reporting a partial list as complete. It lacks an explicit 'when not to use this' condition, so it falls just short of a 5.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds meaningful behavior beyond that: the return envelope structure, the truncation flag and its implications, and the warning not to present a truncated list as complete. It does not mention auth or rate limits, but those are less critical for a read-only usage 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 front-loaded with purpose, then returns, then truncation warning, then args. It is appropriately sized, but 'in an envelope' is slightly redundant with the explicit return shape that follows, and the Args section repeats field names already in the schema.

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

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

With no output schema and zero schema coverage, the description does the necessary work: it explains the return structure and truncation semantics, and documents both parameters. For a simple read-only tool, nothing essential is missing, though the absence of sibling context keeps it short of perfect.

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

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

Schema description coverage is 0%, so the description carries the full burden and does so adequately: it explains limit as maximum rows with a default of 25, and target as a MinIO target name from config that can be omitted for the default. It fully covers both parameters with no obvious missing meaning, though it could specify what targets are available.

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 metric (per-bucket usage in bytes and objects), ordering (biggest first), and delivery format (envelope). It clearly identifies the resource and measurement but does not distinguish this tool from similar siblings such as bucket_info or capacity_rca.

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

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

There is no explicit guidance on when to use this tool versus alternatives like bucket_ls or capacity_rca. The only conditional instruction is about omitting target for the default, which is parameter usage rather than tool-selection guidance.

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