xae_unlink

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

Goes well beyond the annotations: discloses that unlinking is refused when no link exists or when a TwinSAFE end is involved, that the change is in-memory only ('not saved, not activated'), that it runs once, and that the result reports what changed. It also spells out the confirmation-token workflow expected for this destructive 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?

The scope rule is front-loaded in the first sentence and refusals, side-effect status and confirmation requirements follow in a logical order. It is dense but each clause carries information; the 'ITcSysManager::UnlinkVariables' API reference is the one mildly expendable element.

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 destructive, non-idempotent, single-shot mutation with an output schema present, the description covers scope, preconditions, side-effect persistence, and the required confirmation handshake. Nothing an agent needs in order to call it safely is missing; return-value detail is correctly left to the output schema.

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 0%, so the description must carry parameter meaning and largely does: 'variable' must be a full tree path as named in xae_links, and 'target' being null/omitted selects all links. However, the third parameter 'confirm_token' is never named – it is only implied through the tc_request_confirmation call, leaving the link between that call and this field implicit.

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 ('Remove a link') and immediately distinguishes itself from siblings by scope: one link between variable and target, or all links of the variable when target is omitted. References xae_links as the naming source, so the agent can tell it apart from xae_link (creation) and xae_links (read-only table).

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?

Gives clear conditions: omit target to remove every link of a variable, and specifies two refusal cases (no such link, TwinSAFE end). Points to xae_links for path naming and prescribes the tc_request_confirmation pre-step with the exact target format. It stops short of explicitly naming xae_link as the counterpart for adding links, hence a 4 rather than a 5.

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