guardian_audit

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

Since no annotations are provided, the description must carry the full burden of behavioral disclosure. It does reveal two behaviors: the requirement for four review domains for korean_senior rows and the fail-closed behavior when fail_on is set. However, it does not disclose whether the tool is read-only, what it modifies, any authentication requirements, or any side effects. This is insufficient for an audit tool of this complexity.

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 a single sentence that combines two unrelated pieces of information with a semicolon. It is concise but severely under-specified for a tool with 9 parameters. The structure does not front-load the most important information about the tool's purpose or usage; instead it focuses on an edge case about korean_senior rows.

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 a tool with 9 parameters, no annotations, and no output schema, the description is drastically incomplete. An agent has no understanding of what the tool returns, what most parameters do, or what the audit covers. The description only addresses a narrow scenario, leaving the agent to guess about the rest.

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 should compensate by explaining key parameters. It only hints at 'fail_on' by mentioning it in the fail-closed clause, but does not explain its values or purpose. Parameters like run_sca, run_probes, and various report paths are left completely unexplained, making it hard for an agent to know how to set them.

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 states 'Run Guardian' which identifies the action, but it does not explain what Guardian does or why it would be used. The mention of 'korean_senior rows' and 'four review domains' suggests a specific audit context, but without knowing what Guardian does, the purpose remains ambiguous. It distinguishes from siblings only by name, not by functionality.

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 gives a specific condition: 'korean_senior rows require four review domains' and 'fail closed when fail_on is set.' This hints at when this tool might be needed, but it does not explicitly state when to use this tool over alternatives like deep_analyzer_audit or software_composition_audit. There is no guidance on exclusions or when not to use it.

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