nifi_create_processor

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

Annotations carry the safety profile (not readOnly, openWorld, not idempotent, not destructive), and the description adds real behavioral context: free-cell placement when x/y are omitted, and that an overlapping x/y is shifted down with the shift reported in the result. It doesn't mention permissions or that properties are defaulted, but the layout behavior is meaningful disclosure.

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?

Front-loads the action and the sibling routing before the placement details. Two tight sentences, though the layout sentence is dense and could be split for faster scanning.

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?

An output schema exists, so return values need not be explained, and annotations cover the mutation safety profile. For a create tool with many optional fields, the description covers the tricky placement behavior well but is thin on the remaining optional parameters.

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 effectively 0% at the top level, so the description must compensate. It clarifies x/y placement semantics (512x240 free cell, overlap shift) which the schema only partially states, but says nothing about bundle, properties, auto_terminated, scheduling_period/strategy, verbose, or comments, leaving most fields undocumented.

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?

Specific verb+resource ('Add a processor to a process group') plus an explicit sibling contrast ('Prefer nifi_apply_flow_spec for a whole graph'), so the agent can distinguish it from the bulk graph tool without opening a schema.

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?

Explicitly routes the agent to the alternative for whole-graph work, which is a genuine when-to-use signal. It lacks an explicit statement of prerequisites (e.g., that the parent process group must exist) or when-not conditions beyond that one routing rule.

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