create_connector

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

No annotations are provided, so the description carries the full behavioral burden. It reveals that captions and stroke caps/styles are configurable, but never states that this mutates board state, whether the operation fails if items are on different boards or missing, or whether the connector is deletable/reversible — all material for a creation tool.

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?

Two sentences, front-loaded with the core action before the optional-styling notes, with no filler. The reST-style double backticks and embedded example syntax are slightly noisy but do not obscure meaning.

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 needn't be explained, but for a 12-parameter, unannotated creation tool the description is thin: it omits prerequisites (valid board_id, both items existing), the color/stroke field distinctions, and any failure or side-effect behavior. An agent would have to guess at several required-to-styling choices.

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 0% across 12 parameters, so the description must compensate and only partly does: it clarifies caption, end_stroke_cap, and stroke_style. It leaves the ambiguous fields unresolved — notably the distinction between color, stroke_color, and stroke_width, plus font_size and text_orientation — meaning most non-obvious parameters remain undocumented anywhere.

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 opens with a specific verb+resource — 'Connect two items' — which maps cleanly onto create_connector and sets it apart from get/update/delete_connector siblings. It does not explicitly say the items belong to a board or that the result is a connector object, so the object being created is only implied.

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 statement of when to use this versus update_connector, list_connectors, or the create_shape/create_text siblings that might also draw links. The only conditional language concerns optional styling parameters, not tool selection or prerequisites such as both items needing to exist on the same board.

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