diagnose_iam_exposure

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

With no annotations, the description carries full behavioral burden. It does well by explaining group-inherited policy resolution, the MinIO default-deny interpretation of NO_EFFECTIVE_POLICY, finding categories, and worst-first sorting. It does not cover all possible behaviors such as error cases or rank scale details, but for a read-only diagnostic it is suitably transparent.

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

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

The description is well-structured and front-loaded with [READ][risk=low]. It efficiently covers purpose, key behavioral caveats, finding list, sorting, and parameter semantics without unnecessary filler. Every sentence carries informational weight.

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

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

Given there is no output schema, the description admirably explains return content through finding categories, sorting, and truncation behavior. It also addresses complex IAM nuance. The only minor gap is not specifying the output envelope/rank format more concretely, but the description is still complete enough for tool selection and basic 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 for both parameters. It does: limit is described as 'Maximum findings to return (envelope reports truncation)' and target as 'MinIO target name from config; omit for the default.' This adds meaningful guidance beyond the bare schema defaults.

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

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

The opening line 'Ranked IAM findings: admin sprawl and unusable accounts' clearly identifies the tool's resource (IAM) and specific scope (admin sprawl and unusable accounts). It distinguishes itself from sibling tools like iam_users and iam_policies by emphasizing ranked findings and specific finding categories.

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

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

The description provides strong context for when the tool is appropriate (IAM exposure diagnosis, admin sprawl, unusable accounts) and explains key behavior like resolving group-inherited policies. However, it does not explicitly state when not to use it or name alternative tools, so it stops short of full guideline clarity.

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