ue5_connect_pins

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

With no annotations, the description carries the full burden of behavioral disclosure. It does disclose the verification steps (existence, type compatibility, read-back) and the fail-loud behavior for ambiguous titles, which is valuable. However, it does not mention side effects such as whether the change persists, whether the blueprint is saved, or any return value. For a mutation tool, this is a significant gap, but the verification details provide some transparency beyond a simple 'connect' statement.

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 two sentences in English plus a Chinese translation, with no fluff. The primary action is front-loaded, followed by the key verification behavior and a specific usage hint. Every sentence adds information, and the structure is efficient and scannable. The bilingual duplication is a stylistic choice, not a waste.

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 mutation tool with no output schema, the description should cover side effects, prerequisites, and return behavior. It covers the verification and failure modes but does not mention whether the blueprint needs to be loaded, whether connections are immediately applied, or what happens on success. Given the tool's complexity (array of connections with node/pin references), this is incomplete. However, the verification details mitigate some gaps, so a 3 is appropriate.

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 already provides descriptions for both parameters (blueprint_path and connections) with 100% coverage, giving a baseline of 3. The description adds meaningful value by explaining node reference formats (titles or 32-hex GUIDs) and the rejection of ambiguous titles, which is not present in the schema. This extra detail helps agents correctly specify the connections array, raising the score above baseline.

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 clearly states the tool's primary action ('Connect pins') and adds a specific differentiator: triple topology verification (existence, type compatibility, read-back). This distinguishes it from sibling tools like ue5_disconnect_pin and ue5_read_connections, which have obviously different purposes. The verb+resource combination is precise and 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?

The description provides parameter-level guidance (e.g., 'use GUIDs when titles repeat') but does not explicitly state when to use this tool versus alternatives like ue5_disconnect_pin or ue5_read_connections. It implies the use case for connecting pins but lacks explicit exclusion or alternative selection criteria. The guidance about ambiguous titles is useful but is focused on parameter usage rather than tool selection.

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