bp_find_orphaned_nodes

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 returns a structured result with orphaned_nodes and total_orphaned, and indicates nodes are 'safe to remove,' which subtly implies an advisory purpose. However, it does not explicitly state whether the operation has side effects (e.g., loading assets, requiring compilation), nor does it mention error conditions or permission requirements. For a find operation, the read-only nature is implied by 'Find' but not explicitly confirmed.

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 structured with Args, Returns, KB, and Example sections, each serving a distinct purpose. It is not excessively long and front-loads the core definition. The inclusion of return structure duplicates what the output schema presumably provides, but this is a minor 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?

Given the low complexity (two parameters, one required) and presence of an output schema, the description covers all essentials: parameter meaning, example invocation, and KB reference for deeper context. It lacks an explicit mention of required vs. optional parameters, but that is encoded in the schema. Overall, an agent can confidently invoke this tool 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?

Since schema coverage is 0%, the description must compensate, and it does by defining blueprint_path as 'Full asset path or plain name' and graph_name as 'Graph to inspect,' providing more meaning than the bare schema. It also gives a concrete example that demonstrates parameter usage. However, it omits details like the default of graph_name (EventGraph) or how 'plain name' is resolved, though defaults are present 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 the specific verb 'Find' with a precise resource ('nodes in a Blueprint graph that have zero connections of any kind') and further clarifies orphaned nodes as having no input or output links. This distinguishes it from sibling tools like bp_remove_orphaned_nodes (which removes rather than finds) and other find/audit tools. It unambiguously states the tool's function without any ambiguity.

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 implied usage context by noting orphaned nodes are 'a common byproduct of incomplete graph edits,' suggesting this tool is useful during cleanup workflows. However, it does not explicitly state when to use this tool versus alternatives (e.g., bp_find_disconnected_pins), nor does it mention any exclusion conditions. There is no direct comparison to sibling tools.

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