Map findings to compliance frameworks

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

With no annotations provided, the description must carry the behavioral disclosure burden. It does this well by stating that returns are control mappings that are audit evidence, not an attestation of compliance, and by instructing to relay the caveat and avoid presenting as a compliance verdict. It could add read-only / side-effect disclosure, but nothing about the described behavior is hidden or contradictory.

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?

Three sentences with the purpose front-loaded and no filler. The framework list is long but necessary for specificity, and the caveat instruction earns its place as a critical usage rule.

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 description covers purpose, both input paths, output semantics, and a user-facing caveat, while an output schema exists to document return values. The main remaining gap is precise parameter-level guidance for `frameworks` and the file input shape, but the tool can still be selected and invoked correctly from this description.

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 clarifies the intent of `findings` and `files`, and the first sentence implies what `frameworks` selects. However, it does not explain the format of the `files` object, the exact shape of `findings`, or whether `frameworks` is required / optional / defaults to all covered frameworks.

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 opens with a specific verb and resource ('Map Terraform findings to the compliance controls they speak to') and enumerates the exact frameworks covered. It clearly distinguishes itself from scan_terraform by showing it maps existing findings or can accept files 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?

Pass `findings` from scan_terraform, or `files` to scan and map in one call' gives explicit input modes and a clear when-to-use context. It does not explicitly name sibling alternatives like framework_coverage for when not to use this tool, but the guidance is specific enough.

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