Add work item relation

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

With no annotations provided, the description carries the full burden. It discloses that the tool is a write operation requiring confirmation, but it does not mention side effects, reversibility, or behavior on existing relations. The confirm requirement is already in the schema, so the only added context is 'write tools,' which is vague. This is minimal but not misleading.

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 a single sentence with two clauses, front-loading the primary purpose and then stating the key prerequisite. There is no fluff, and it is appropriately concise for the information it conveys.

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 7 parameters and no output schema, the description is sparse. It does not explain the meaning of expectedRevision (likely optimistic concurrency), comment, or the specific behavior of each relation type. It also does not describe the response or error conditions. An agent would need to infer too much to call it correctly, making this incomplete.

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 57%, leaving comment, expectedRevision, and relation without descriptions (though relation has an enum). The description clarifies the relation parameter by listing values, but that is redundant with the enum. It does not explain the purpose of comment, expectedRevision, or project beyond schema defaults. The description adds little semantic value beyond the schema.

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 action: 'Link two work items' and enumerates the relation types (parent, child, related, dependency, duplicate). This clearly differentiates it from other work-item tools like update_work_item or create_work_item, which handle different operations. The purpose is 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 a prerequisite ('Requires write tools and confirm=true') but does not mention when to use this tool versus alternatives, nor does it contrast with sibling tools. It implies usage for linking work items but offers no exclusions or alternative routing, which is a gap given the large sibling set.

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