bp_validate_blueprint

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions aggregating compile diagnostics and returning a health score but does not state whether invoking the validator triggers an actual compilation, whether it modifies any assets, or whether it is read-only. The name 'validate' suggests non-destructive behavior, but the description does not explicitly confirm this.

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 distinct sections for purpose, args, returns, KB reference, and an example. It is longer than minimal but each part adds value – the argument explanations, output specification, and example usage are all useful. Minor redundancy exists (e.g., 'compile diagnostics' repeated in the opening and returns), but overall it is efficient.

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 description is complete for the tool's complexity. It specifies all three parameters with semantics, details the full return structure (including types and meaning), provides a concrete usage example, and references a KB doc. Given an output schema exists (the description itself serves as the output schema), nothing critical is missing for an agent to use it correctly.

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?

The schema has zero description coverage across all three parameters. The description compensates fully with an 'Args' section explaining each parameter: blueprint_path (full asset path or plain name), include_graph_validation (run per-graph structural checks), and include_variable_check (check for unused variables). This adds meaningful semantic context beyond the bare type information in the 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: 'Top-level Blueprint validator: compile + graph structure + variable usage.' It clearly states it aggregates these three categories into a health score, which distinguishes it from narrower siblings like bp_validate_graph (graph only), bp_get_compile_diagnostics (compile only), and bp_find_unused_variables (variable check only).

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 labels itself 'Top-level' and implies a comprehensive check, but it does not explicitly state when to use this tool versus individual validators. There is no mention of alternatives or conditions like 'use this for a holistic health overview, or use bp_validate_graph for structural-only checks.' The usage is implied rather than explicit, leaving the agent to infer the appropriate context.

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