compile_blueprint_and_report

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

No annotations are provided, so the description carries the burden. It discloses that the tool wraps the compile in editor progress and a transaction, returns a safe_to_continue flag, and lists the exact output fields. It does not mention side effects like whether the transaction is committed or rolled back, or whether compilation modifies the asset, but the transaction mention and structured result provide meaningful behavioral context beyond the schema.

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 well-structured with a one-sentence summary, a short behavioral note, an Args section, a Returns section, a KB reference, and an example. It is slightly long but every section earns its place; the example and KB pointer are useful. The front-loaded summary is clear.

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 tool has an output schema, so return values are covered. The description adds the safe_to_continue flag semantics, the transaction/progress wrapping, and a KB reference. It is complete enough for an agent to call it correctly, though it could clarify whether the transaction is committed and whether the compile is saved to disk.

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 explains blueprint_path accepts a full asset path or plain asset name, include_graphs controls graph node/orphan summaries, and graph_names is an optional allowlist with empty meaning all graphs. This adds real meaning beyond the bare schema titles, though it could be more explicit about the default behavior of graph_names when null.

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 compiles a Blueprint and returns graph-aware diagnostic evidence, with a specific verb ('Compile'), resource ('Blueprint'), and output ('diagnostic evidence'). It distinguishes itself from the sibling compile_blueprint by noting it wraps the compile in editor progress and a transaction and returns structured diagnostics, making it a higher-order report tool.

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 explains the tool's role in higher-order workflows and mentions it wraps the compile in editor progress and a transaction, implying it is the diagnostic/report variant rather than a bare compile. It does not explicitly name alternatives like compile_blueprint or bp_compile, but the context signals and the 'B.2 report tool' framing give clear usage context. No explicit when-not-to-use guidance is given.

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