geck_esp_delete_refs_by_base

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

With no annotations available, the description carries the full burden of behavioral disclosure. It does reveal the central behavior: matching is based on the base FormID, not the reference's own FormID, and matching records are deleted. However, it does not mention whether the deletion is permanent, whether backup=true creates a restore point, or how plugin_name scopes the deletion, which are important for a destructive operation.

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 is a single compact sentence with no filler. It front-loads the action and object, then states the matching condition efficiently. Every word contributes to understanding what the tool does.

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 tool with four parameters and no annotations, the description is incomplete. It omits the purpose of backup, which plugin is affected by plugin_name, and why game_dir is needed. The presence of an output schema covers return-value documentation, but the side-effect model and input semantics are not sufficiently explained for confident invocation.

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%, so the description must clarify the parameters. It only adds meaning to base_form_ids by connecting it to 'NAME/base FormID'. The backup, game_dir, and plugin_name parameters are not explained at all, leaving an agent to guess their roles from names and default values alone.

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 clearly states the action ('Delete'), the resource ('placed records'), and the exact selection criterion (NAME/base FormID matches one of the given base IDs). This makes the tool easy to distinguish from the sibling geck_esp_delete_refs, which is not explicitly scoped to base FormIDs. The purpose is specific and immediately recognizable.

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 implies this tool should be used when the goal is to remove all placed instances matching particular base FormIDs. However, it does not explicitly say when to choose this over geck_esp_delete_refs or another reference-editing tool, and it provides no exclusions or prerequisites. The usage context is inferable but not stated.

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