assign_system_template_bulk

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

With no annotations, the description carries the full burden, and it delivers the single most important behavioral fact: success=True is not a per-device success count, FortiManager returns no per-device result for this scope-member ADD, and the client raises on any non-zero code. That is a genuine partial-failure disclosure an agent could not infer elsewhere. It still omits lock requirements, overwrite behavior for devices already bound to another template, and idempotency.

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 purpose is front-loaded in one clean sentence, but the Returns block is a docstring dump that partly restates the output schema and includes an internal artifact reference ('same shape as #78's device-group bulk tools') that costs tokens without helping an agent. The core caveat inside it is worth keeping; the packaging is not.

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 an unannotated bulk mutation touching many devices, the description covers the success-semantics trap well but leaves out acquisition of an ADOM lock, whether existing assignments are replaced, and what happens to other devices if one fails. Adequate to call correctly, thin on consequences.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description must compensate, and it does for the hardest parameter: the devices array is shown with its key structure and a concrete example ({"name": "dev1", "vdom": "root"}), which the schema entirely lacks given its bare additionalProperties:string items. 'adom: ADOM name' and 'template: System template name' add little beyond the field names, keeping it below 5.

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 opening sentence states a specific verb and resource plus the bulk scope ('Assign a system template to multiple devices'), which implicitly separates it from the singular assign_system_template and from assign_sdwan_template_bulk. It never names the sibling alternative explicitly, so the differentiation is inferable rather than stated.

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 through the word 'multiple' -- an agent can guess that assign_system_template is the single-device path, but the description never says so, nor does it state prerequisites such as needing the ADOM unlocked or the template to already exist. No when-not guidance at all.

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