relations_relate

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

With no annotations, the description carries the behavioral burden and does disclose meaningful asymmetry for duplicate_of relations ('LOSER — the card that dies' vs. 'SURVIVOR') and source attribution. It does not mention idempotency, whether re-asserting a relation errors or replaces, permissions, or other side effects, so the disclosure is useful but incomplete.

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 opens with a one-sentence purpose and then uses a clean Args list with one line per parameter. There is no filler, and the formatting makes the parameter semantics scannable for an agent.

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 five-parameter mutation tool with no annotations, the description covers all parameters, the controlled vocabulary, and the crucial duplicate_of directionality; the output schema likely covers return values. It could be more complete by explaining the other relation types' directionality and the effect of re-asserting an existing relation, but it is not missing anything essential for a basic correct call.

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%, but the description fully compensates by explaining every parameter, listing all valid values for rel, and giving concrete examples for src_id and source. It also adds critical semantic meaning for src_id and dst_id in the duplicate_of case, which the schema alone does not convey.

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 precise action ('Assert a typed relation between two findings') and names the resource ('findings'), with a list of valid relation types that make the operation concrete. It does not explicitly differentiate from sibling tools relations_unrelate and relations_query, but 'assert' plus the enumerated relation types make it identifiable.

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 usage is implied: call this when creating a typed relation, as opposed to relations_unrelate or relations_query for removing or inspecting relations. However, there is no explicit when-to-use or when-not-to-use guidance, and no sibling tools are named as alternatives.

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