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, so the mutation profile is covered. The description adds nothing beyond that: it does not warn that repeated calls create duplicate links (non-idempotent), nor state permission requirements, despite being the natural place to do so.

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, correctly stating verb and operands first. It is efficient, though 'etc.' leaves the accepted itemtype set open rather than bounded.

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. However, for a non-idempotent linking mutation with three required parameters, the description omits the lifecycle context (existence prerequisites, duplicate-link behavior) that an agent needs to call it safely, leaving it minimally viable.

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 100%, so the schema already documents documents_id, itemtype and items_id, and the description only echoes the itemtype examples ('Ticket, KnowbaseItem'). With the schema doing the heavy lifting, baseline 3 is appropriate; no format, ID-space or type-mismatch guidance is added.

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 a link') and both resources (document and item), and enumerates example target types (Ticket, KnowbaseItem). It implicitly separates itself from glpi_create_document (creates the document) and glpi_get_document_item/glpi_list_document_items (reads links), but never explicitly routes the agent among those 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?

There is no when-to-use guidance, no stated prerequisites (e.g. that the document must already exist, likely via glpi_create_document, and that the target item must exist), and no mention of the read-side siblings glpi_get_document_item or glpi_list_document_items for verification.

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