bp_find_disconnected_pins

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 does document the return shape (disconnected_pins[] with fields and total_disconnected), but it never explicitly states that this is a read-only diagnostic or mentions prerequisites such as the Blueprint being loaded or whether it triggers a compile. The read-only nature is only inferred from 'Find all...'.

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 Args, Returns, KB, and Example sections, all information-dense and free of filler. The core action is front-loaded in the opening sentence, and each section adds practical value such as path format, return fields, and an invocation example.

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?

Given that an output schema exists and all three parameters plus return fields are documented, an agent has enough information to call the tool correctly. The main gap is the absence of explicit when-to-use/alternative guidance, but that is covered in the usage dimension; otherwise the definition is complete for a read-only diagnostic.

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%, but the Args block fully compensates: blueprint_path is documented as 'Full asset path or plain name', graph_name gets its default value, and pin_type_filter is explicitly enumerated as 'exec', 'input', or 'all'. Every parameter receives meaningful semantics beyond the bare titles 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 uses a specific verb ('Find') and resource ('disconnected exec or input pins in a Blueprint graph'), and even lists the exact output fields. It is clearly differentiated from sibling diagnostics like bp_find_unreachable_nodes or bp_find_orphaned_nodes because the target resource—pins—is explicit.

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 no explicit guidance on when to use this tool versus the many related diagnostics in the sibling list, such as bp_find_unreachable_nodes, bp_find_orphaned_nodes, or bp_validate_graph. The intended usage is only implied by the name and example, with no stated exclusions or alternatives.

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