ck_validate

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

With no annotations, the description carries full burden. It declares read-only behavior ('no changes are applied') and states it returns a validation result with findings. It does not disclose rate limits, permission requirements, or output format details, but sufficiently covers key behavioral traits for safe invocation.

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 paragraph of 8 sentences, front-loaded with purpose and behavioral info. It is concise for the amount of content, though slightly structured; bullet points could improve scannability.

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 13 parameters, no output schema, and many sibling tools, the description covers purpose, behavior, key parameter roles, and usage instructions. It lacks explanation of what 'CK policy' entails or the validation result format, but overall provides sufficient context for correct tool selection and 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 coverage is 85%, so baseline is 3. The description adds value by explaining how parameters like kind, source_type, domain_pack, and requested_capabilities affect policy routing and trust-boundary checks, going beyond the schema's field descriptions to provide actionable guidance.

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 clearly states the tool validates proposed code, config, shell commands, or text against CK policy before execution. It explicitly distinguishes from sibling tools like ck_execute_code by noting it is read-only and precedes execution, and directs to ck_finding for recording blocked findings.

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 instructs to call ck_validate before writing files, running shell commands, or executing generated code, and specifies not to proceed if blocked findings are returned. It lacks explicit mention of when not to use or alternatives for non-validation tasks, but provides clear context for its primary use case.

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