bp_validate_graph

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

With no annotations, the description carries the safety burden and clearly labels the operation as 'Inspect' (read-only). It is transparent about what is checked, that results are independent of compile status, and what StructuredResult will contain; it does not claim any mutation or side effects. It does not discuss permissions or failure modes, but that is not critical for a validation tool.

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 front-loaded with the purpose, then checks, args, returns, KB pointer, and example in clearly labeled sections. Every section adds orienting information and there is no 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 two-parameter inspection tool with an output schema, the description is largely complete: parameters, expected output fields, a KB reference, and a call example are all present. It would be more complete with explicit routing to sibling diagnostic tools, but an agent can safely select and invoke this tool from the information provided.

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 0%, and the description partially compensates: blueprint_path is clarified as 'Full asset path or plain name' and an example is given. graph_name only restates the schema's title/default ('Graph to inspect (default 'EventGraph')'), so added meaning is thin for that parameter.

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 opening sentence names the specific operation ('Inspect one Blueprint graph'), the resource, and the focus ('structural health issues'), and the next sentence enumerates concrete checks. This distinguishes it from per-issue siblings like bp_find_orphaned_nodes and from compile-oriented tools via 'independent of compile status.'

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 implies use for structural-health validation of a single graph and notes it is useful even when the graph doesn't compile, but it does not say when to prefer this aggregate check over bp_validate_blueprint, bp_find_disconnected_pins, bp_find_unreachable_nodes, or bp_find_orphaned_nodes. There are no when-not-to-use or alternative routing statements.

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