delete_edge

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered; the description adds genuinely new behavior: it returns whether an edge was removed, and a nonexistent identifier is not an error but a no-op report. That not-found semantics is exactly the kind of detail annotations cannot express. It does not mention permissions or side effects on the connected thoughts.

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 short sentences, front-loaded with the action and resource, followed by when-to-use and then return semantics. No filler or restatement of the name.

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 need not be spelled out, yet the description still flags the removed/not-removed outcome and the non-error no-op case, which is the key ambiguity for a delete. The only gap is whether deleting the edge leaves the two thoughts intact and whether any permission is required.

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?

There is one parameter at 0% schema description coverage, so the description must carry the burden. "By its identifier" confirms edge_id selects the edge, but adds no format, source, or where-to-obtain guidance (e.g., from list_edges). Adequate but thin for a fully undocumented parameter.

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 and resource (delete an edge between two thoughts) plus the lookup key (by its identifier), so the agent knows exactly what is being removed. It does not explicitly contrast itself with the closest siblings (link_thoughts for creation, list_edges/get_edges for inspection), but the semantics are unambiguous on their own.

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?

"Use this to remove a relationship that is wrong or no longer wanted" gives a clear condition for invocation, and the mental model of edge-vs-thought deletion is clear from the resource named. It stops short of naming an alternative tool or stating when-not to use it (e.g., to modify rather than remove, relink instead).

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