skill_repair_broken_blueprint

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

With no annotations to lean on, the description fully discloses side effects: it applies repairs, recompiles the Blueprint, runs post-mutation verification, and supports a dry_run safety mode. It also explains that non-deterministically repairable issues are collected in repairs_skipped rather than silently ignored, and documents max_repairs as a safety cap.

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 organized with a one-line summary, numbered steps, a limitations note, Args, Returns, KB pointer, and example. It is detailed but every section earns its place, and the most important purpose statement 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?

For a complex skill tool with no annotation coverage, the description provides everything needed: input semantics, behavior, limitations, return fields, a KB reference, and a concrete example. It even documents the not-repairable cases so an agent can predict outcomes before calling.

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 has the full burden of explaining all three parameters. It does so clearly: blueprint_path accepts either a full asset path or plain name, dry_run toggles reporting-only behavior, and max_repairs caps how many auto-repairs are applied. This goes well beyond the bare input schema.

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 opens with a specific verb and resource: 'Diagnose a Blueprint and apply deterministic repairs automatically.' It then names the exact orchestration steps (compile diagnostics, structural validation, repair plan, apply repairs, recompile, verify), which clearly distinguishes it from lower-level siblings like bp_repair_exec_chain and bp_remove_orphaned_nodes.

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 strong context for when to use the tool: when a Blueprint has deterministic, auto-repairable structural issues like orphans or disconnected exec chains. It clearly states which issue types are not repaired and are instead reported in repairs_skipped, but it does not explicitly name alternative sibling tools or say 'use X instead' when only auditing or compiling is needed.

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