Compile a document family

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

Annotations already declare destructiveHint=true, non-idempotent and non-read-only, so safety is covered. The description adds genuinely useful context the annotations cannot: the returned handle is process-scoped, dies on restart, and is evicted after 64 retained handles, forcing recompilation. It still does not say what the compile writes or whether recompiling is cheap, which keeps it short of a 5.

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, no filler: artifact/return value first, then the handle lifecycle caveat, then the alternative route. Every sentence earns its place and the most decision-relevant information is front-loaded.

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?

With an output schema present, the description needn't explain returns, and it correctly focuses on what structured data cannot convey: handle lifetime and the sibling split. The remaining gap is behavioral detail around the destructive/non-idempotent profile (what is written where, cost of recompiling), which matters for a 12-parameter compile 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 description coverage is 100% across 12 parameters, including the nested pdf_vt_job hierarchy and profile requirements, so the schema carries the load. The description only reinforces the inline HTML/CSS nature of the input and adds nothing about individual parameters (profiles, intents, timestamps), which is the baseline 3 case.

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?

States a specific verb and resource ('Compile inline HTML/CSS') and names its output artifact (compile_id plus template statistics), which immediately distinguishes it from the render tools. It also explicitly differentiates itself from fullbleed_compile_vdp, so an agent can route without opening either schema.

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?

Gives a clear when-to-use ('for repeated calls to fullbleed_render_compiled') and names an alternative (fullbleed_compile_vdp) with the condition that selects it (single variable-data job without retaining a handle). It does not address the other compile-adjacent siblings such as fullbleed_render or preflight presets, so routing is clear for the main fork but not exhaustive.

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