nifi_schedule_process_group

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

Annotations already declare idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds one genuinely useful behavioral detail beyond the annotations: only authorized processors are affected, which signals partial application under permission limits. It does not say what happens to processors already in the target state or what stopping a live group interrupts.

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?

One sentence, front-loaded with the operation and scope, zero filler. Appropriately sized for a two-parameter action.

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 safety. But for a bulk mutation that can halt data flow across a whole group, the description omits the operational consequence of STOPPED and the partial-success behavior implied by 'authorized', leaving the agent with a thinner picture than a group-level action warrants.

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% for the single nested param, so the description must compensate. It does name both allowed states (RUNNING/STOPPED) and the target scope (process group), which maps onto the enum and process_group_id. It adds no format or identifier details beyond that.

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?

States the resource (process group), the operation (bulk setting RUNNING/STOPPED for every authorized processor), and the scope (all processors, not one). Clear verb+resource, though the leading 'Bulk RUNNING or STOPPED' is slightly telegraphic rather than a clean verb. It does read as distinct from the single-target nifi_set_run_status sibling.

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?

No when-to-use or when-not-to-use guidance. The obvious alternative, nifi_set_run_status, is a sibling but is never named or contrasted, so the agent must infer that 'group-wide' vs 'single component' is the selection criterion.

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