audit_infra_security

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

No annotations are provided, so the description must fully disclose behavior. It mentions checking misconfigurations and a budget gate, but does not specify whether the tool is read-only, if it modifies resources, what authorization is needed, or how results are returned. The term 'budget gate' is ambiguous—does it block or just report? More detail is needed.

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

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

The description is very short, which can be a positive for conciseness, but it is a fragment lacking verbs and structure. It could be rephrased as a clear sentence, e.g., 'Audit IaC for security misconfigurations and enforce a budget limit on estimated monthly cost.' The current brevity sacrifices clarity.

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 tool has 3 parameters, no output schema, and no annotations. The description is insufficient to understand the full scope and behavior. For a security audit tool, it should detail what types of misconfigurations are detected, how the budget gate works, and what the output contains. The current description is incomplete.

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 should compensate by explaining key parameters. It alludes to 'budget gate' (likely budget_limit_usd) and 'IaC misconfigs' (infrastructure_content), but does not describe cloud_provider or the format of infrastructure_content. Users are left guessing about required input expectations.

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

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

The description 'IaC misconfigs + budget gate on estimated monthly burn' provides a general idea of the tool's function: auditing infrastructure-as-code for security misconfigurations and checking estimated costs against a budget. However, it is vague and does not clearly distinguish from sibling tools like audit_cloud_cost (cost audit) or audit_code_safety (code safety). A more precise verb and resource specification would improve clarity.

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

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

No guidance is provided on when to use this tool versus alternatives. Given sibling tools that also perform audits (e.g., audit_cloud_cost, audit_code_safety), the description should explicitly state the context for using this tool, such as 'Use for security posture assessment of IaC with cost gates.'

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