ik_compile

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

With no annotations provided, the description carries the full burden and discloses key behaviors: it returns success, diagnostics, and the hex/IR artifact, and it states that `import std/...` resolves automatically. It doesn't cover error specifics or side effects, but 'diagnostics' implies feedback and the overall behavior is clearly conveyed.

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 three sentences, front-loaded with the primary action. Each sentence provides necessary context—what the tool does, what it returns, and when to use it—without filler or redundancy.

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 no output schema and no annotations, the description adequately covers return values, emit modes, and the verification use case. Remaining gaps include the `report` parameter and explicit relationship to sibling tools, but overall it provides sufficient context for an agent to select and invoke the tool.

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 60% and the description adds some value by clarifying that `source` and `path` are alternative inputs and that output format depends on `emit`. However, it does not explain the `report` parameter, which is undocumented in both schema and description, so it doesn't fully compensate for the coverage gap.

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 'Compile ik source (inline `source` or a `path`) with the real ik8b compiler,' clearly identifying the verb, resource, and method. Mentioning that it produces Intel HEX or SSA IR artifacts distinguishes it from sibling tools like ik_check or ik_simulate, and the phrase 'real ik8b compiler' sets it apart from reference or tutorial tools.

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 explicitly instructs 'Use this to VERIFY any ik code you generate,' providing a clear when-to-use directive. It does not explicitly name alternatives or exclusions, but the verification context implies its role relative to other ik_* tools.

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