cloud-audit

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

No annotations provided, so description carries full burden. It adds valuable behavioral context that the output is 'copy-paste ready' AWS CLI and Terraform HCL, explaining the practical utility. However, it omits operational details like error handling for invalid check_ids, caching behavior, or permission requirements that annotations would typically cover.

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?

Excellent structure: purpose front-loaded in sentence 1, behavioral detail (copy-paste ready) in sentence 2, Args section for parameter specifics. No filler text; every sentence conveys distinct information about scope, output format, or parameter values.

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?

Adequate for a single-parameter tool with an output schema (documented in structured data). The description covers the essential inputs and explains the output's nature without needing to detail the full return structure. Minor gap: lacks cross-reference to list_checks for obtaining valid check_ids.

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

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

Schema has 0% description coverage (only 'title: Check Id'), so description must compensate. It successfully adds semantic meaning ('The check ID') and critical format examples ('aws-iam-001', 'aws-s3-001') showing the namespace-ID pattern. Could be improved by noting the check_id source (e.g., from list_checks).

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

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

Description opens with a specific action ('Get') and resource ('remediation details'), immediately clarifying scope by specifying the output format (CLI command + Terraform code). This distinguishes it from sibling tools like get_findings (which returns findings) and list_checks (which enumerates checks).

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?

Implies usage context by requiring a 'specific check' and documenting the check_id parameter with examples. However, lacks explicit guidance on when to use this tool versus siblings (e.g., 'use after list_checks to obtain a check_id' or 'use when you need fix instructions vs. just the finding description').

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