bucket_exposure_audit

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

With no annotations provided, the description carries the full behavioral burden. The '[READ]' prefix proactively declares this as a read-only operation, which is important given siblings like bucket_delete and set_bucket_policy are mutations. It also discloses that results are 'ranked' and 'riskiest first', and that a 'cause + action' is provided per finding — meaningful behavioral details beyond a simple audit listing.

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 well-structured with a bracketed [READ] tag, a declarative opening sentence stating purpose and ranking, a compact list of audit dimensions, a user-focused use-case line, and a short Args section. It is efficient and front-loaded with the core purpose. Minor redundancy: the ranking fact appears twice ('Ranked... riskiest first' and 'fastest answer'), which is slightly repetitive.

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 an audit tool with 0% schema coverage, no output schema, and no annotations, the description does substantial work: it defines the full scope of checks, discloses read-only status, explains parameter semantics, and frames the ranking behavior. It could add clarity on the return format (since there's no output schema) and edge-case behavior around the limit, but these gaps are modest for a straightforward audit tool.

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

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

Schema description coverage is 0%, so the description must compensate. It documents both parameters: 'limit: Maximum buckets to audit (default 100)' and 'target: MinIO target name from config; omit for the default.' The descriptions add the semantic meaning that the schema's bare names (limit, target) lack. However, it doesn't explain the unit or consequence of the limit (e.g., what happens if there are 200 buckets — is only 100 audited, or skipped?), and the target's meaning relies on config context. Adequate but not exhaustive.

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

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

The description clearly states the verb ('scores every bucket') and the resource (bucket-exposure findings), and explicitly defines what it checks: anonymous/public read and write policy statements, missing default encryption, versioning off, and no lifecycle. It positions itself as the fastest answer to an exposure question, distinguishing it from related tools like bucket_policy_get, bucket_versioning_get, etc.

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

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

The description clearly states when to use this tool ('the fastest answer to is anything in my object storage exposed?') and enumerates the specific exposure dimensions. It doesn't explicitly name sibling alternatives or state when not to use it, but the audit-vs-single-get distinction is implicitly clear given sibling names like bucket_policy_get and bucket_versioning_get.

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