nvr_delete_export

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

With no annotations provided, the description carries the full burden and does well: it flags the operation as a WRITE, names both gates (VIGI_NVR_ALLOW_WRITES=true and confirm_write=true), and discloses path confinement so the agent knows the blast radius. It stops short of stating whether deletion is reversible or what happens when the named file does not exist, which are the remaining behaviors an agent would want.

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?

Two tight sentences with zero filler. The core action leads, followed by the naming constraint, then the write gate. Every clause carries information an agent needs to call the tool correctly.

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 no explanation, and the description covers the action, parameter constraint, and write authorization. For an unannotated destructive tool it is nearly complete; a note on reversibility or missing-file behavior would close the last gap.

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 50%: confirm_write is heavily documented in the schema, but the required 'name' parameter has only a title of 'Name'. The description compensates by defining what that name must be (a generated export filename, path-confined), which the schema does not say. That added meaning for the undocumented parameter lifts this above the baseline.

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, and scope: delete ONE file from the export directory, with the path-confined constraint and the requirement that the name be a generated export filename. This cleanly separates it from the sibling nvr_purge_exports (bulk delete) and nvr_get_export/nvr_list_exports without needing to open any schema.

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 usage context by constraining the name to a generated export filename (implying you must have listed/identified an export first), and it states the write preconditions. However, it never explicitly names the alternative tool (nvr_purge_exports) or states when to prefer deleting a single file versus purging all exports. Usage is inferable but not spelled out.

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