bp_add_node

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

With no annotations provided, the description carries the full burden. It clearly discloses that the tool creates a node (a mutation), returns a structured JSON result with specific output fields (node_id, node_name, node_type, pos_x, pos_y), and lists the supported node types. It does not mention potential prerequisites (e.g., blueprint existence, graph validity) or error behavior, but given it's a creation tool, the core side effects are transparent. This is good but not exhaustive.

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 long but well-organized with clear sections: purpose, node_type values, node_params examples, return values, and args. It front-loads the core purpose and uses bullet-like formatting for readability. It could be trimmed (e.g., the example ends with 'bp_add_node()' without arguments), but overall it is structured efficiently for the complexity it covers.

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 tool's complexity (13 parameters, many node types), the description is incomplete. It omits documentation for several parameters, leaves the relationship between node_params and individual fields unresolved, and provides a truncated example. The return value description is solid, and the KB reference adds context, but the gaps in parameter coverage make it insufficient for an agent to correctly invoke the tool in all cases.

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 only documents 6 of the 13 schema properties (blueprint_name, node_type, graph_name, node_params, position_x, position_y). It leaves event_name, node_class, target_class, custom_params, function_name, variable_name, and blueprint_path unexplained. Moreover, it introduces a node_params dict with examples that overlap with individual schema fields (e.g., target_class, function_name) but doesn't clarify the relationship between the dict and those separate fields, creating ambiguity. The description fails to compensate for the schema's lack of documentation.

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 precise statement: 'Add a node to a Blueprint graph and return its stable node_id.' It then enumerates the supported node types and states it is the primary node-creation tool wrapping multiple specialized add_blueprint_* functions, which clearly distinguishes it from siblings like add_blueprint_event_node and add_branch_node.

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 identifies itself as the primary node-creation tool and explicitly names the wrapped alternatives (add_blueprint_event_node, add_blueprint_function_node, etc.), implying it should be used for general node creation. It also notes the returned node_id is for bp_connect_pins and bp_inspect_node, providing downstream context. However, it doesn't explicitly state when to prefer this over the specialized tools beyond being the unified interface, so it falls short of a 5.

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