set_relation

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

No annotations exist, so the description carries the whole burden. It usefully discloses that a superseded relation 'stays stored and readable; it is closed, not deleted' – genuine destructive-behavior context. However, it omits the concurrency contract implied by the required expected_revision, whether 'remove' is reversible, and any error/permission behavior for a mutation 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?

Three tight sentences with the core action front-loaded and the trickier supersession semantics packed into the second. Minimal waste, though the temporal-validity sentence is dense enough to be broken up.

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 an unannotated, 9-parameter mutation tool with no output schema, the description covers the most subtle behavior (close-not-delete, temporal validity) but leaves too much of the required-parameter contract and alternative-tool routing unstated to be fully self-sufficient.

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 9 parameters, so the description must compensate and largely does not. It clarifies valid_from, valid_until and supersedes, but leaves id, target_id, predicate, resolve_reference and the required expected_revision unexplained beyond their patterns.

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?

States a specific verb+resource: 'Add or remove a typed relation between two existing entries', and adds the pending-reference resolution case. It distinguishes itself from write-style siblings like set_tags, though it never names the closest sibling (set_unresolved_relation), leaving that differentiation implicit.

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 explains what supersedes and valid_from/valid_until mean when adding, but gives no guidance on when to use this tool versus set_unresolved_relation, set_tags, or relations. No exclusions or preconditions are stated, so the agent must infer the routing.

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