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

Annotations already mark this as a non-read-only, destructive operation. The description adds useful behavior beyond that: duplicate connections with the same type are a no-op, and the 'introduced' relationship has strict spelling and direction semantics. It does not explain why destructiveHint is true or what destructive side effect could occur.

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 with the core operation and examples, then moves to edge-type semantics. It is somewhat verbose in the final warning about 'intro' or 'referral', but that warning carries real behavioral information.

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 three-parameter mutation tool with full schema coverage and annotations, the description covers directionality, relationship naming, duplicate behavior, and the special introduction case. It does not discuss permissions, failure modes, or return behavior, but no output schema exists and the core call semantics are clear.

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 100%, so the schema already documents all three parameters. The description still adds value by explaining where object IDs come from, illustrating from/to direction with examples, and specifying the exact 'introduced' relationship spelling and direction.

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 two graph objects with a directed edge — and gives concrete examples such as file-to-project and person-to-company. It clearly distinguishes the operation from creation or searching by explaining that it links existing objects.

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 tells the agent to use object IDs returned by create, search, or list operations, and gives a precise rule for introduction edges. It does not explicitly name alternatives such as disconnect_graph_objects for removal, but the intended 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.