Queue Create

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

With no annotations, the description carries the full burden and does well: it discloses that class_name is refused rather than silently dropped, and explains the underlying Drupal queue-service resolution order. It does not state permission requirements or what happens on a duplicate queue name, but the refusal contract is genuinely useful behavioral 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?

Purpose is front-loaded in the first sentence, and the rationale for the class_name refusal follows. The second paragraph is somewhat long for a two-parameter tool, but every sentence explains a real constraint rather than restating the 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?

An output schema exists, so return values need not be described. Purpose, the key parameter quirk, and the underlying service-resolution behavior are covered. Only secondary details (auth/permissions, duplicate-name handling) are absent, which is acceptable for a create tool of this scope.

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. It thoroughly explains the non-obvious class_name parameter (why it exists and why it is rejected), which is exactly the missing semantic information. queue_name is left entirely unexplained, but its meaning is self-evident from the tool name.

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 ('Create a queue') plus the outcome ('make it ready to accept items'), which clearly separates it from siblings like queue_list, queue_run, queue_info, and queue_delete. An agent can route to it 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?

Usage is implied by the name and by the contrast with the other queue_* siblings, and the class_name discussion hints at what the tool will not accept. There is no explicit statement of when to prefer this over alternatives or any prerequisite/context (e.g. settings.php configuration needing to be in place first).

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