nifi_create_connection

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=true. The description adds meaningful behavioral guidance about relationships for processor sources vs port sources and about cross-group port wiring. It does not disclose other behavioral details such as permissions, duplicate handling, or side effects beyond the annotations.

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, short, and structured into a general rule followed by a special-case paragraph. Every sentence adds useful information for constructing a connection, especially the less obvious child-group case.

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 tool has annotations for its safety profile and an output schema, so return values need not be described. The description covers the critical input semantics that the schema does not fully explain, particularly parent/group routing for child groups. It is not exhaustively complete for every optional connection setting, but it is sufficient for correct invocation in the common and cross-group 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?

The schema gives sparse descriptions for several fields, and the description compensates by explaining key semantics for source_type, relationships, source_group_id, destination_group_id, and parent_id in the child-group wiring case. It does not explain every parameter such as name, verbose, or queue thresholds, but it covers the most non-obvious required wiring semantics.

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 states a specific verb and resource: 'Connect a source to a destination.' It also clarifies two important source/destination cases. However, it does not explicitly distinguish this tool from sibling nifi_update_connection, which would require naming the alternative or saying when to create instead.

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?

It gives clear usage rules: 'Processor sources need relationships; port sources take none,' and it explains the special child-group wiring case involving OUTPUT_PORT, INPUT_PORT, parent_id, and group IDs. It does not explicitly cover when to use this tool rather than nifi_update_connection, so it stops short of full alternative routing.

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