save_entry_ref

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

No annotations, so the description carries the full behavioral burden, and it is thin. It does not explain what determines create vs update (identity key — source+target+relation_type?), whether an existing edge is overwritten or duplicated, whether the label is replaced on update, or what permissions are required for a graph mutation.

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?

A single front-loaded sentence with zero filler. It is efficient, though the brevity is partly under-specification rather than disciplined compression.

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?

A mutation tool with no annotations, no output schema, and a non-obvious upsert semantic needs more than one clause. The agent is left unsure what happens on conflict, whether the call is idempotent, and what is returned.

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 all four parameters including the relation_type value list are already documented in the schema. The description adds only the graph-edge framing and nothing about parameter interaction (e.g., required source/target despite zero required fields declared).

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 pair and resource: create/update a link between two entries, qualified as a graph edge. The distinction from the sibling add_link is not addressed, and 'create or update' leaves the upsert trigger ambiguous, but the operation itself 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?

No when-to-use guidance, no prerequisites, and no mention of the obviously competing siblings add_link, get_link, or list_entry_refs. The agent must infer from the name alone whether this or add_link is the right call.

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