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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds the version-aware hint ('whether this is 2.x'), which is useful context, but does not disclose anything further about behavior or edge cases.

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?

Two short sentences with zero waste, and the identification content is front-loaded ahead of the call-timing advice.

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?

With an output schema present, return values need no exposition, and for a zero-parameter informational tool the stated purpose plus call timing is everything an agent needs.

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 tool takes zero parameters, so the baseline of 4 applies; there is nothing for the description to clarify beyond 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?

States a specific resource (NiFi version/build) and its distinguishing output ('whether this is 2.x'), which lets an agent separate this informational probe from all the sibling operation tools. The verb-resource pairing is implicit but unambiguous.

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 prescribes when to call it: 'Call first on a new session.' No alternative tool competes for this purpose, so no exclusion is needed.

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

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

The annotations declare the safety profile (not read-only, not idempotent, open-world, non-destructive), and the description adds substantial context beyond that: @-prefixed property resolution, service enablement order, boolean/number coercion, null semantics, per-item outcome values, ref addressing, which items are eligible for deletion, and rollback hints. This is exactly the added behavioral detail the annotations do not cover.

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-loaded with purpose and the sibling-preference rule, and the dense result/error semantics are all non-redundant information. However the prose runs long and some sentences are run-ons that pack multiple distinct behaviors together, which slightly hurts scanability for an agent.

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?

For a single-parameter, high-complexity, open-world mutation tool with 0% schema coverage, the description is complete: it covers spec structure, value conventions, error/cause taxonomy, unknown-outcome handling, and rollback guidance. An output schema exists, yet the error-path semantics it adds are genuinely necessary because they are not structured data.

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%, so the description carries the full burden and does so: it documents top-level keys, process_group keys, the @-service resolution convention, list-or-single acceptance for auto_terminated/relationships, and JSON-to-NiFi text conversion. That is far more than the bare nested schema provides.

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?

Opens with a specific verb and resource ('Create a complete flow from a declarative spec') and enumerates the component kinds it builds (process group, services, processors, ports, connections). It also explicitly distinguishes itself from siblings via 'Prefer this over many create_* calls', which is exactly the kind of routing an agent needs.

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?

Gives a clear preference rule: use this instead of many create_* calls. It also tells the agent to check again before retrying when an outcome is 'unknown'. It does not state explicit when-not conditions or name the specific create_* siblings to fall back to, 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.

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

Annotations already cover readOnly=false, idempotent=true, destructive=false, so the bar is lower, yet the description adds real behavioral context beyond them: the default maps to the UI's 'Apply recursively', descendants' existing contexts are replaced, and the operation is atomic ('NiFi checks every group before changing any, so an error means no group was rebound'). It omits auth/permission requirements and error/report format, keeping it from a 5.

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-loaded with the core action and its purpose, then behavioral detail in two compact paragraphs. Sentences carry distinct content (purpose, recursive default, atomicity, non-recursive option), though verbose/verbose-field prose could be trimmed.

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 the description covers the essential behavior a caller needs for this mutating tool. It is nearly complete, with the only gap being explicit auth/permission or failure-mode guidance.

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?

With schema coverage reported at 0%, the description compensates for the ambiguous parameters by explaining that 'null unbinds' the group (parameter_context_id) and that apply_recursively=false scopes the bind to only this group. It leaves verbose and process_group_id unaddressed in prose, so it only partly covers the parameter set.

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 a specific verb and resource ('Bind a parameter context to a process group') and gives the effect ('so #{name} references resolve'), which lets an agent distinguish this from sibling CRUD tools like nifi_create_parameter_context. It does not explicitly route the agent away from any sibling, so it stops short of a 5.

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 implies the use case (resolving #{name} references) and implicitly guides parameter choices ('null unbinds', 'apply_recursively=false binds only this group'), but gives no explicit when-to-use/when-not and does not name alternatives or prerequisites. Usage is left to inference.

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

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.

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

Annotations already disclose the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true). The description adds one useful behavioral fact: enablement is optional and controlled at creation time. It omits what a mutation-only context might need, such as whether duplicates can result from idempotentHint=false or what authorization the process group requires.

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?

A single front-loaded sentence with no filler; the create action and its scope lead. It is arguably too terse rather than padded, but every word present earns its place.

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, but for a create tool with seven properties at 0% schema coverage the description is thin. Key inputs required to invoke it correctly (service_type, name, properties) go unmentioned.

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%, so the description carries the full burden, yet it only obliquely references two fields ('in a process group' for parent_id, 'enable it' for enable). The required service_type and name, plus properties/bundle, are never explained, leaving agents to infer them from bare titles.

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 names a specific verb (Create) and resource (controller service) scoped to a process group, so an agent immediately understands the operation. It does not, however, distinguish itself from close siblings like nifi_update_controller_service or nifi_set_controller_service_state, so it stops short of a 5.

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?

There is no guidance on when to choose this over related tools such as nifi_create_processor, nifi_list_controller_service_types (to discover service_type), or nifi_set_controller_service_state. The mention that enabling is optional hints at a relationship with the state-setting sibling but never states an alternative.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false and openWorldHint=true, covering the safety/idempotency profile. The description adds no behavioral context beyond that—nothing about uniqueness of names, error behavior, or side effects. With annotations carrying the disclosure burden, the description contributes essentially nothing extra.

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?

Two short, front-loaded sentences with zero filler. The core action comes first and the follow-up hint comes second.

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. Still, for a create tool the description omits name-uniqueness constraints and failure modes, leaving the agent with only the minimal action statement plus one next-step pointer.

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 single top-level 'params' object parameter has no schema description (0% reported coverage). The description says only 'with parameters', which does not explain the nested name/value/sensitive/description fields or clarify the object shape. Although the nested $defs carry useful detail, the top-level parameter is left undocumented and the description does not compensate.

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 a specific verb+resource: creating a parameter context with parameters. It also hints at downstream use by naming nifi_bind_parameter_context, which helps separate it from read/update siblings. It is clear but does not explicitly contrast with nifi_update_parameter_context or nifi_get_parameter_context.

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 implies the workflow ('Bind it to a group with nifi_bind_parameter_context'), giving a next-step cue. But it offers no guidance on when to create vs. update an existing context, prerequisites, or what happens if a context with the same name already exists.

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

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

Annotations already declare the mutation profile (readOnly=false, destructive=false, idempotent=false, openWorld=true), so the bar is lower, and the description still adds real behavior: omitting x/y picks the next free 424x288 cell, and an overlapping x/y is shifted down with the shift reported in warnings. It does not mention permissions or parameter-context interaction, keeping it from a 5.

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?

Three short lines, front-loaded with the core action and the placement rule. Every sentence carries information an agent would otherwise have to guess.

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 described, and the description still flags the warnings field for the overlap case. For a mutation tool with full annotation coverage and a parameter-context option documented in the schema, this is nearly complete.

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?

With the schema carrying no description for x/y, the description compensates by defining their default placement behavior and the overlap-shift rule. It says nothing about name, parent_id, comments, or verbose, so the less tricky parameters are left to 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?

States a specific verb and resource ('Create an empty process group') and immediately clarifies scope by telling the agent to build flows inside one of these rather than on root. That scope statement distinguishes it from sibling mutators like nifi_create_processor or nifi_create_connection 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?

'Build every new flow inside one of these, not on root' gives explicit when-to-use guidance with a clear negative case. It stops short of naming an alternative tool for the root case, so it is clear context rather than full routing.

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

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.

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds that the response includes anonymous and permissions flags, which is useful signal about what the call reveals, but says nothing about auth failure behavior or what happens when credentials are unset.

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?

A single compact sentence with no filler, delivered up front. Every clause adds information about the tool's output.

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?

With no parameters and an output schema that documents the return shape, the description only needs to frame what the tool reports, which it does. It could note that this reflects the caller's own credentials rather than arbitrary users, but nothing essential is missing.

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 tool takes no parameters, so per the rubric the baseline is 4. The description correctly implies a zero-input query with no filtering needed.

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 names a specific concern — the identity the configured credentials authenticate as — plus the anonymous/permissions flags it surfaces. That is enough to separate it from siblings like nifi_about or nifi_get_health, though the phrasing is slightly cryptic rather than a clean verb+resource statement.

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?

There is no guidance on when to call this versus nifi_about, nifi_get_health, or other read tools, and no mention of prerequisites or when the anonymous flag matters. Usage is only implied by the tool name.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is known. The description adds real value beyond them: the precondition states required for a safe delete and the fact that the result echoes id, kind and revision rather than the deleted entity. Behavior is well disclosed.

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-loaded with the deletable scope, then the parameter-context precondition, then the return behavior. Every sentence carries information with no filler, though the two-paragraph split could be tightened.

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 the brief note about the result format is sufficient rather than mandatory, and the destructive/safety profile is covered by annotations. The remaining gap, component_id acquisition and failure modes on precondition violation, is minor for a single-param delete tool.

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%, so the description must compensate. It enumerates the kinds that map to the 'kind' enum values, adding meaningful context there, but says nothing about 'component_id' format or how to obtain it. Partial compensation only.

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 specific verb (Delete) and enumerates exactly which resource kinds can be removed (processor, connection, controller service, ports, process group, parameter context). This scope precision lets an agent distinguish this from all the create/update/get siblings without opening the 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?

It states preconditions for each component kind (stopped processor, empty connection, disabled service, ports with no connections, empty process group) and an explicit rule for parameter contexts (no bound process group). That effectively tells the agent when deletion is admissible, though it does not name an alternative tool or clarify failure behavior when preconditions are unmet.

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

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

Annotations already flag destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds meaningful context beyond annotations: 'Data loss' (confirming severity) and the ordering dependency with connection deletion, which the annotations do not convey.

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?

Three terse sentences, front-loaded with the destructive action and its consequence, with zero wasted words.

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 the description covers the destructive consequence and the prerequisite workflow. Only the parameter's role is left unaddressed, a minor gap for a single obvious id.

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% and the description never mentions the single required parameter connection_id, so it does not compensate for the undocumented schema. The parameter is fairly self-evident, but the description contributes no meaning about it.

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 a specific verb ('Drop') and resource ('every FlowFile on a connection'), making the effect unambiguous and clearly distinguishable from the read-only sibling nifi_list_queue. An agent knows exactly what this does without opening the 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?

Adds a concrete prerequisite: 'Required before deleting a non-empty connection,' which tells the agent when this tool is part of a workflow. It doesn't name an explicit alternative, but the usage context is clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint, so the safety profile is covered. The description still earns credit by disclosing a non-obvious behavior: properties, run schedules, or network interfaces that NiFi reports invalid are masked in the component they are invalid on, consistent with other reads.

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 operation is front-loaded in the first sentence, and the masking caveat is a compact second paragraph. Both parts earn their place, though the masking sentence is somewhat dense.

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-value explanation is not required, and the description does note the output matches the UI export. However, as a read tool with an undocumented include_services flag and no routing versus nifi_get_flow, it is only minimally complete.

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% and the description adds no meaning for either parameter. In particular, include_services (default false) is entirely undocumented, leaving the agent to guess what 'services' are included and when to enable them; process_group_id is self-evident by name only.

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 names a specific verb+resource ('Download a process group as a versioned flow snapshot') and adds a helpful anchor ('same JSON the UI exports'). It is clear what operation is performed, but it never explicitly distinguishes itself from close siblings such as nifi_get_flow, nifi_import_flow, or nifi_replace_flow.

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?

There is no explicit when-to-use guidance, no conditions for choosing this over nifi_get_flow, and no mention of prerequisites or exclusions. The implied usage (export/download) is inferable but never stated.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the behavioral note that after_id is a cursor rather than a time, which prevents a common misuse, but omits ordering/pagination behavior and the limit cap of 100.

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-loaded and short: the purpose and the diagnostic trigger come first, followed by the single gotcha about the cursor. The fragmented 'not a time' clause is slightly clipped but every sentence earns its place.

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 described. The description covers purpose, a usage trigger, and the one parameter pitfall an agent is likely to get wrong, leaving only minor gaps around limit defaults and ordering.

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 reported as 0% at the top level, so the description carries extra weight; it does explain the critical after_id cursor semantics. However, it says nothing about limit (default 30, max 100) and only indirectly gestures at the compact-vs-verbose distinction that the schema documents.

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 names a specific verb+resource ('Recent NiFi bulletins') and disambiguates the content type as errors/warnings. It is clear what the tool returns, though it does not explicitly contrast itself with siblings such as nifi_get_health or nifi_get_flow.

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?

'Use after a flow misbehaves' gives a concrete diagnostic trigger, which is more than nothing, but there is no guidance on when to prefer this over nifi_get_health or other diagnostic tools, and no exclusions or prerequisites.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description still adds real value by disclosing the return contents (state, validation errors) and, importantly, that secrets are redacted — a security-relevant behavior not present in 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?

A single front-loaded sentence fragment with zero filler; the resource is stated before the returned fields. Terseness borders on cryptic, but every clause earns its place.

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-value detail is not required in prose. The description names the key returned elements and the redaction behavior, leaving only the verbose toggle unexplained — a minor gap for a one-parameter read tool.

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 reported at 0%, and the description never mentions the 'verbose' parameter (which toggles full redacted JSON vs compact view) nor the service_id format. The schema's own enum-free properties carry the load, so the description does not compensate for the coverage gap.

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 a specific resource ('One controller service') and enumerates what it returns: state, validation errors, properties. The singular 'one' plus the service_id requirement distinguishes it from nifi_list_controller_services, though it never names that sibling explicitly.

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?

Usage is only implied: fetching details for a single service by id. There is no explicit when-to-use guidance, no mention of the verbose flag, and no routing away from nifi_list_controller_services or nifi_get_processor_definition for related lookups.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered. The description adds that the default return is a 'compact outline', which is genuinely useful behavioral context. It stops short of covering size/pagination or depth limits of the outline, so a 3 is appropriate.

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?

A single tight sentence with zero filler, and the resource is front-loaded. It is efficient, though slightly under-specified rather than perfectly economical.

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-value detail is not the description's burden, and annotations cover the safety profile. Still, for a tool whose nearest siblings include export/import/replace flow operations, the description should say why you would call this read-only outline instead, and it does not.

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?

Top-level schema coverage is 0% (the only exposed param is an unlabeled 'params' object), yet the nested ProcessGroupIn $def does document both fields, including the 'root' default and the verbose/compact distinction. The description adds nothing beyond that, so it neither compensates for the awkward top-level wrapping nor improves on the nested docs.

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 phrase names the resource (process group) and enumerates what the outline contains (child groups, processors, connections, ports), so an agent can infer it returns a structural view. However it is a bare noun phrase with no verb and no differentiation from siblings like nifi_export_flow or nifi_apply_flow_spec, which also deal with flow structure. Adequate but not sharp.

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?

There is no when-to-use or when-not-to-use guidance, no mention of the alternative of exporting the flow (nifi_export_flow) or of viewing a single processor (nifi_get_processor). The agent must guess from the name alone that this is the lightweight topology view.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered externally. The description adds nothing behavioral beyond that - it never mentions the compact-vs-verbose output switch, redaction of sensitive values, or default root-canvas scope, which are the traits an agent would actually need.

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?

It is a single short fragment with no filler, but it is under-specified rather than concise - no verb, no scope, no qualifiers. Every word earns its place yet the whole sentence is too small for the tool's job.

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-value detail is not required, but the description still omits the two behavioral facts an agent must know: that the result is scoped by process group and that verbose swaps the compact view for full redacted JSON. For a read-only health probe this leaves a meaningful gap.

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 reported as 0%, so the description must compensate for the two parameters (process_group_id, verbose), and it does not mention either. An agent learns nothing about scoping or the verbosity flag from the text; the only usable parameter documentation lives in the nested $defs.

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 fragment enumerates the report contents (state counts, queued connections, validation-error processors), which tells an agent roughly what comes back, but it never states the action or scope and is silent on which process group is inspected. It also does not differentiate itself from overlapping siblings such as nifi_get_flow, nifi_get_bulletins, or nifi_list_queue.

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?

There is no when-to-use guidance, no statement of what this replaces (e.g. instead of paging through nifi_list_queue or nifi_get_flow for problems), and no mention that it can be scoped to a process group. Usage is only loosely implied by the word 'health'.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the lower bar applies, yet the description still adds real value: sensitive values are redacted and process-group bindings are included. It does not discuss error behavior for an unknown/invalid id, keeping it below a 5.

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?

A single tight sentence with the resource and the notable return detail (redaction, bindings) front-loaded. No filler or 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?

An output schema exists, so return-value explanation is not required, and annotations carry the safety profile. The description covers the key behavioral nuance (redaction) and scope, though it omits how to obtain a parameter_context_id (e.g., via nifi_list_parameter_contexts) and the verbose option.

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 low (0%), but the single required parameter is a self-evident identifier for the context being fetched, which the description's 'One parameter context' supports. The description says nothing about the `verbose` flag or its effect, leaving that entirely to the schema description ('Return full redacted JSON instead of the compact view').

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?

Names a specific resource (a single parameter context) and states what it returns (parameters with redacted sensitive values, plus bound process groups). The singular 'One' implicitly distinguishes it from sibling nifi_list_parameter_contexts, but it is a noun phrase with no verb and never names that alternative explicitly, so it falls short of 5.

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?

Usage is only implied: fetching 'One' context versus the sibling list tool is inferable from naming convention, and no prerequisites or alternatives are stated. There is no explicit when-to-use or when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so safety is covered. The description does add one genuine disclosure beyond the structured data: "secrets redacted", which tells the agent not to expect sensitive property values. It says nothing about behavior for a missing/invalid component id, which is the remaining gap.

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?

It is a single short fragment with no filler, which is structurally efficient, but it is under-specified rather than concise — there is no verb and no complete sentence. It reads as a note rather than a specification.

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?

With an output schema present, return values need not be re-explained, yet the description lists them anyway; the annotations cover the safety profile. For a one-parameter read tool this is close to adequate, but the component_id semantics and error behavior remain unaddressed.

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 reported as 0%, so the description is expected to carry parameter meaning. It does not: the only parameter, component_id, is never explained (format, where to obtain it, error on unknown id), and the verbose flag is left entirely to the schema. A bare 2 reflects that gap.

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 fragment names a specific resource (one processor) and enumerates what is returned: state, validation errors, properties. Combined with the tool name, an agent can distinguish it from nifi_list_processor_types (enumerate types) and nifi_get_processor_definition (type schema) without opening either schema. It stops short of a full verb-resource sentence, keeping it out of the 5 tier.

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?

There is no when-to-use guidance, no statement of prerequisites, and no routing to alternatives such as nifi_get_processor_definition or nifi_update_processor. The agent must infer usage purely from the name and the returned-field list.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, fully covering the safety profile, so the description owes only incremental context. It adds none: no mention of where the coordinates come from, whether the definition is cached, or what happens on an unknown type.

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?

A single tight clause with no padding. It is front-loaded with the most useful content, though its fragment form makes it less immediately parseable than a verb-led sentence would be.

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?

Because an output schema exists, return values need not be re-explained, and annotations cover safety. What is still missing for a read-only lookup is how to obtain the four required coordinates and how this call relates to the list/get siblings, so the definition is only minimally complete.

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?

Top-level schema description coverage is 0% and the single nested object requires group/artifact/version/type_name, only three of which carry even brief schema descriptions. The description supplies no parameter meaning or example values to compensate, leaving the agent with an under-documented lookup key.

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 names the resource ('one processor type') and enumerates what is returned (property descriptors, relationships, scheduling), but it is a bare noun phrase with no verb, so it never actually states that the tool retrieves the definition. An agent can infer the purpose, but the intent is implied rather than declared.

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?

There is no when-to-use guidance at all. Nothing tells the agent how this differs from nifi_list_processor_types (enumerate types) or nifi_get_processor (fetch a running instance), nor that the required group/artifact/version/type_name identifiers come from those tools.

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

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

Annotations already declare non-read-only, non-idempotent, non-destructive, open-world behavior. The description adds one genuinely useful behavior beyond them: that placing a card can shift existing cards clear. However, it omits permission requirements, idempotency implications of re-importing the same snapshot, and what the compact vs. verbose return actually contains.

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?

Two short sentences, front-loaded with the core action and followed by the placement rule. No wasted words, though the placement detail could be folded into a tighter clause.

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 formatting needn't be explained, but for a mutation tool with three required parameters and zero schema descriptions, the definition leaves the agent without enough to construct a valid snapshot or parent reference.

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% and the nested params object carries six fields (x, y, verbose, snapshot, parent_id, group_name). The description only glosses x/y placement behavior and says nothing about the required parent_id, group_name, or the snapshot payload format, so it fails to compensate for the coverage gap.

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: importing a versioned flow snapshot as a new child process group. This distinguishes it from sibling tools like nifi_create_process_group and nifi_replace_flow, though it never explicitly names an alternative to differentiate itself.

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 only guidance is about placement ('omit x/y to take the next free cell'), which is a geometry rule, not a when-to-use rule. There is no indication of when to choose this over nifi_replace_flow, nifi_apply_flow_spec, or nifi_create_process_group.

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

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

Annotations already disclose that this is a non-destructive, idempotent mutation. The description adds substantial behavioral detail about the resulting layout, including row spacing, fork/join routing, self-loop placement, and child group arrangement, which helps an agent understand what the operation does beyond its safety profile.

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 first sentence is a clear lead, but the rest is dominated by pixel-level layout rules and routing edge cases that are not needed for tool selection or invocation. These details crowd out more important information such as the input parameter and usage context.

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. However, the description omits the only input parameter and any usage context, meaning an agent still lacks critical information for invoking the 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?

The schema has 0% description coverage and the single parameter, process_group_id, is not mentioned in the description at all. The agent receives no help understanding what value to supply or what entity it identifies.

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 first sentence states a specific action for a specific resource type: laying out processors and child process groups. It distinguishes the tool from CRUD siblings by its layout focus, though it never explicitly names a sibling alternative or says 'process group' in the description itself.

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 provides no when-to-use guidance, no prerequisites, and no comparison to alternatives such as get_flow or create_connection. It only describes how the layout is performed, leaving the agent to infer when this tool is appropriate.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered without the description's help. The one genuinely additive fact is '(includes inherited)', which tells the agent the result set is broader than the group's own services — useful scope context. Beyond that, nothing is said about result ordering, size, or the compact-vs-full payload distinction.

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?

A single economical sentence with the scoping qualifier placed immediately after the resource. It is front-loaded and wastes nothing, though it is a fragment rather than a complete, self-contained statement of the 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?

The tool is a simple read-only list with an output schema, so return-value explanation is rightly omitted and the annotations carry the safety burden. What is missing for a complete definition is any usage framing relative to the many sibling list/get tools and any acknowledgement of the two input fields that shape the response.

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 description mentions no parameters at all. The nested schema does carry descriptions for both fields ('verbose' = full redacted JSON vs compact view; 'process_group_id' = id or 'root'), so the agent is not fully stranded, but the context signal reports 0% schema description coverage at the top level and the description does nothing to compensate for the default-'root', minLength-1, or verbosity 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 names the resource (controller services) and the scoping unit (a process group, including inherited services), which lets an agent distinguish it from nifi_list_controller_service_types (types, not instances) and nifi_get_controller_service (single instance). The verb is only implied by the tool name rather than stated, so it falls short of a fully explicit 'list X for Y'.

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?

There is no when-to-use guidance and no routing to alternatives. An agent must infer from the name that this is the enumeration counterpart to nifi_get_controller_service, and nothing tells it when listing inherited services is preferable to fetching a single service or listing types.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is fully covered by structured data. The description adds nothing behavioral beyond what the annotations and schema already state (no pagination/limit behavior, no notes on what 'installed types' means in a live NiFi instance), so it provides no incremental value.

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?

Two tight sentences with no filler; the core action is front-loaded and the filter capability follows immediately. Nothing is padded or redundant.

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 safety profile. However, for a discovery tool whose siblings include both processor-type and controller-service listing variants, the absence of alternative routing and of any guidance on limit/verbose leaves clear gaps.

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 description mentions the class-name substring filter, which corresponds to the type_filter parameter, but says nothing about 'limit' or 'verbose'. Reported schema description coverage is 0% (only two sub-properties carry inline descriptions), so the description only partially compensates for the documentation gap.

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 a specific verb and resource ('List installed controller-service types'), which cleanly separates it from the sibling nifi_list_processor_types by resource. It does not, however, explicitly call out that distinction for the agent, which is the one realistic confusion point among the listed siblings.

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 never says when to use this tool versus alternatives (e.g., nifi_list_processor_types for processor types, or nifi_list_controller_services for existing instances vs. available types). Usage is only inferable from the name — the discovery step before nifi_create_controller_service — with no explicit guidance or exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely new information beyond the annotations by disclosing that sensitive parameter values are redacted in the results, which is important for an agent interpreting the output.

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?

Two short sentences with no filler; the core action is front-loaded and the redaction caveat follows immediately. Every sentence earns its place.

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 described, and annotations cover the read-only/idempotent profile. The redaction note closes the main behavioral gap; only the relationship to the singular get_parameter_context sibling is unaddressed.

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 tool takes no parameters, so the baseline is 4. Schema coverage is 100% and there is nothing for the description to clarify about inputs.

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 ("List parameter contexts"), which is unambiguous on its own. It does not, however, explicitly distinguish itself from the sibling nifi_get_parameter_context (singular retrieval), leaving the plural/singular split to inference.

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?

Usage is only implied: the name and verb make it clear this enumerates all parameter contexts, and with zero parameters there is little ambiguity about how to call it. There is no explicit guidance about when to prefer this over nifi_get_parameter_context or nifi_create/update/bind_parameter_context.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=true and destructiveHint=false, so the safety and side-effect profile is fully covered structurally. The description adds only the discovery-to-lookup workflow, saying nothing extra about result shape, pagination default of 25, or the compact-vs-verbose behavior. Adequate given the annotation coverage, but not rich.

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?

Two short sentences, front-loaded with the action and followed immediately by the filtering and follow-up guidance. No filler, and the most decision-relevant detail (the routing to nifi_get_processor_definition) comes last but is not buried.

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 an output schema exists, the description need not explain return values, and annotations carry the safety profile. The discovery workflow and filter hint are sufficient for correct invocation, though a note on result volume or the verbose flag would round it out.

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 description mentions substring filtering on class name, which maps to type_filter, but the schema already documents that field as a case-insensitive substring with examples. The limit (default 25, max 100) and verbose parameters get no mention in the description, leaving half the arguments uncovered outside 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?

States a specific verb and resource ('List installed processor types') that clearly separates it from siblings like nifi_list_controller_service_types and nifi_get_processor_definition. An agent can identify the tool's role without opening the 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 describes the intended workflow - filter by class-name substring, then call nifi_get_processor_definition - which tells the agent this is a discovery step feeding a follow-up lookup. It does not state when NOT to use it or contrast with other list tools, but the chaining context is clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds the empty-delete-blocked precondition, which is useful context, but does not say whether the operation is sampling/paginated or how FlowFiles are selected.

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?

Two short sentences, zero filler, with the scoping precondition placed second. It is efficient and front-loaded, though the terseness is close to under-specification.

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. Still, the description leaves the one required parameter undocumented and does not clarify the ambiguous 'sample' operation, leaving gaps for a read tool with an open-world hint.

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% and the single required parameter connection_id is never mentioned in the description. With the schema and the description both silent, an agent gets no format or sourcing guidance for the one input it must provide.

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 a specific verb (sample/list) and resource (FlowFiles on a connection queue), which separates it from the destructive sibling nifi_empty_queue. However, 'sample' is slightly ambiguous versus the annotation title 'List connection queue', so the verb is not as crisp as it could be.

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 supplies a real precondition ('Connection must not be empty-delete-blocked'), which tells the agent when the call is valid. It never names alternatives (e.g. nifi_empty_queue) or states when not to use this tool, so usage is implied rather than explicit.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false and idempotentHint=false, so 'Destructive' largely restates structured data. The added 'Prefer a sandbox PG' recommendation is genuine value beyond annotations, but it still omits what exactly gets destroyed (existing PG contents) and whether the operation is reversible.

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?

Three terse, front-loaded sentences with no filler. The action is stated first, risk second, mitigation third – every sentence earns its place.

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 described, and annotations cover the safety profile. Still, for a destructive overwrite of a process group, the description does not explain what existing content is replaced or how it relates to the sibling import/apply tools.

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% and the two inner fields (process_group_id, snapshot) carry no descriptions. The description only echoes 'flow snapshot' from the schema; it adds no format, structure, or sourcing detail for the snapshot payload, leaving the parameter under-explained.

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 a specific verb and resource: 'Overwrite an existing process group with a flow snapshot.' Clear what it does, but it does not differentiate itself from close siblings like nifi_apply_flow_spec or nifi_import_flow, which an agent would need to choose between.

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?

'Prefer a sandbox PG' gives a safety-oriented usage hint, which is useful context. However, it never states when to pick this tool over nifi_import_flow or nifi_apply_flow_spec, so the alternative-selection guidance is only implied.

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

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.

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and non-destructive, so the safety profile is covered. The description adds no behavioral context beyond that, but with annotations present the bar is lower and the description doesn't contradict them.

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?

A single tight sentence with the resource scope front-loaded and zero filler. Nothing is wasted.

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-value explanation is not needed. But the query syntax/limits and the verbose toggle are unexplained in the description, leaving the 0% parameter coverage unmitigated for a search tool whose match semantics matter.

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 description adds one useful semantic beyond the schema: the query can match by name OR id, which the raw schema does not state. However, it says nothing about the verbose flag or the format/syntax of the search string, so it only partially compensates for the low schema description coverage.

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 a specific verb (search) and enumerates the resource types (processors, groups, other components) plus the keying (name or id). It distinguishes itself from the get_* siblings by being a search rather than a fetch, though it doesn't name an alternative explicitly.

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 guidance is given. With siblings like nifi_get_processor, nifi_get_flow, and nifi_list_processor_types, an agent must infer on its own when to search versus fetch or list. No prerequisites or exclusion conditions are stated.

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

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

Annotations already declare idempotent=true and destructive=false, so the safety profile is covered. The description adds genuine behavioral context beyond that by disclosing the prerequisite that referencing processors must be stopped before disabling, which affects whether a call will succeed.

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?

Two short sentences, zero filler, with the core action front-loaded and the constraint immediately after. Every sentence earns its place.

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?

With annotations carrying the safety profile and an output schema present, the description need not explain return values. It covers the action and the key constraint adequately, though it could note the distinction from nifi_update_controller_service, which handles property changes rather than state.

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%, so the schema contributes nothing beyond titles. The description's enable/disable framing maps loosely onto the ENABLED/DISABLED enum, but it says nothing about the service_id or the nested params wrapper, leaving a gap that the self-explanatory enum partially offsets.

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 pair and resource — 'Enable or disable a controller service' — which immediately tells an agent this is a state toggle rather than a configuration change. It does not explicitly distinguish itself from nifi_update_controller_service, so it falls short of a 5.

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?

'Referencing processors must be stopped to disable' gives a concrete operational precondition for the disable path, which is real when-to-use guidance. It stops short of naming alternatives or stating when-not-to-use, so it is not a full 5.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds nothing beyond restating the state enum — it doesn't say whether stopping a processor discards in-flight FlowFiles, whether RUN_ONCE completes and reverts, or what a partial failure looks like for a mutation tool.

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 verb and resource, with no filler. Every clause earns its place by pinning down scope and the state domain.

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 needn't be described, and annotations cover idempotency and safety. However, for a state-transition mutation on a live data flow, the description omits operational consequences and error behavior, leaving it only minimally complete.

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% and the single param is a nested object whose two fields (component_id, state) are undocumented in the schema. The description compensates partially by naming the valid state values, but component_id's meaning (which component, format) is left entirely to inference.

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 a specific verb ('Set') and resource ('one processor') and enumerates the four target states, so the agent knows exactly what the tool does. It implicitly distinguishes itself from group-level siblings like nifi_schedule_process_group by scoping to 'one processor', but never names those alternatives explicitly.

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?

Usage is implied by the 'one processor' scope and the state list, but there is no explicit guidance on when to use this versus nifi_schedule_process_group (group-level) or nifi_set_controller_service_state (services). No prerequisites or exclusions are stated.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true and destructiveHint=false, so the safety profile is covered; the description usefully adds that only provided fields are sent (partial semantics) and that NiFi checks component state only when a destination changes. That is real behavioral value beyond the annotations, though permissions or side effects on queued FlowFiles are not covered.

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?

Two short sentences, front-loaded with the purpose, then the partial-update rule and the running-flow caveat. No filler; every sentence earns its place.

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, but with 0% schema coverage the description should specify acceptable formats for the expiration and backpressure fields and mention the verbose/connection_id parameters. The partial-update and state-check notes are helpful but the parameter documentation gap remains.

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%, so the description carries the burden; it names three of the five fields (name, backpressure, FlowFile expiration) but omits 'verbose' and 'connection_id', and gives no value formats for the string fields (e.g., '1 GB' or '30 sec'), which an agent needs for back_pressure_data_size_threshold and flow_file_expiration.

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 a specific verb (Change) and resource (a connection) plus the three mutable aspects (name, backpressure, FlowFile expiration), which clearly separates it from nifi_create_connection and nifi_empty_queue. It stops short of explicitly naming the sibling alternatives, so it lands at 4 rather than 5.

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 'Sends only the fields you set' clause implicitly tells the agent this is a partial-update tool and the running-flow note gives context, but there is no explicit when-to-use/when-not guidance or routing to alternatives (e.g., nifi_create_connection for new connections). Usage is implied rather than stated.

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

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

Annotations cover the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), and the description adds non-obvious behavioral constraints beyond them: partial-update semantics ('sends only the fields you set'), the disabled-state requirement, and that processor references survive the update. That is exactly the kind of context annotations cannot express.

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?

Three short sentences, front-loaded with the action, followed by the operational constraint. No filler, no repetition of the name or annotations.

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?

Output schema exists so return values need no explanation, and the description fully covers the workflow an agent needs to execute the update correctly (disable, update, re-enable, references preserved). Nothing material is missing.

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?

Top-level schema description coverage is 0%, though the nested properties/verbose fields carry their own descriptions. The description compensates with the key semantic ('sends only the fields you set'), but omits that null removes a property and says nothing about service_id or the verbose toggle.

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 a specific verb+resource+scope: 'Change a controller service's properties or name in place.' This clearly separates it from nifi_create_controller_service (creation), nifi_get_controller_service (read), and nifi_set_controller_service_state (state toggling). An agent can select it without opening any 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 names the prerequisite sequence and the sibling tool: disable via nifi_set_controller_service_state, stop referencing processors first, update, then re-enable. This is a when-to-use and a when-not-to-use (cannot update an enabled service) in one compact block.

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

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

Annotations declare the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true, openWorldHint=true), so the description's job is to add beyond that. It does: it discloses the significant side effect that NiFi restarts referencing components itself, plus the two-call workflow needed to flip the sensitive flag. It does not mention permission requirements or that removal is irreversible in practice.

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?

Three short sentences, front-loaded with the mutation verb set, and each sentence carries a distinct rule (action scope, restart side effect, name-collision and sensitivity constraints). No padding or restatement of the tool name.

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?

With an output schema present, return values need not be explained, and the annotations cover the safety profile. The description fills the remaining gaps an agent needs before mutating: what the tool changes, the restart side effect, and the two-call sensitivity constraint. The only omission is which parameter context is targeted, which the name and parameter_context_id field imply.

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 description adds a genuine cross-parameter constraint that the schema cannot express — that the same name may not appear in both parameters and remove — and explains the remove-then-re-add pattern for sensitivity changes. The per-field details (verbose, description, value) are left entirely to the schema, but the inter-parameter semantics are the valuable part and are present.

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 names a concrete verb set (add, change, remove) and resource (parameters), which is specific enough that an agent immediately knows this mutates parameter definitions. It stops short of naming the sibling tools (nifi_create_parameter_context, nifi_get_parameter_context) or explicitly stating the scope is a single parameter context, so sibling differentiation relies on the tool name alone.

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 supplies real invocation conditions — a name cannot appear in both parameters and remove, and changing a parameter's sensitivity requires a remove-then-add sequence across two calls. However, there is no guidance on when to choose this over nifi_create_parameter_context or nifi_get_parameter_context, so the when-to-use story relative to alternatives is only implied.

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

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

Annotations only cover the safety profile (non-read-only, idempotent, non-destructive, open-world). The description adds genuinely non-obvious behavior: partial update semantics ("sends only the fields you set"), the STOPPED requirement, and the collision-resolution rule where an overlapping move is shifted down and reported in the result. That is substantive context beyond the structured fields.

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?

Three tight sentences, front-loaded with the action and scope, then the precondition, then an edge-case behavior. No filler and nothing repeated from the schema or annotations.

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?

Output schema exists, so return values need no explanation, and the description covers the mutation preconditions and an edge case. It leaves open what the verbosity/precondition interaction looks like on failure and doesn't document several accepted fields, a minor gap for a mutation tool.

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 nested payload, so the description has to compensate, and it does: it names the four changeable aspects (properties, name, schedule, position) and clarifies partial-update behavior. It omits comments, auto_terminated and verbose, which remain undocumented, so it is not fully compensating.

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 specific verb ("Change") and resource ("processor") and enumerates the mutable surface: properties, name, schedule, position. That clearly separates it from nifi_create_processor, nifi_get_processor and nifi_delete_component, though no sibling is named explicitly.

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 states a concrete precondition: property, name and schedule changes require the processor to be STOPPED, while a position-only move does not. That is real when-to-use guidance, but it never points to the sibling that stops the processor (e.g. nifi_set_run_status) or says what happens if the precondition is violated.

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