Safety annotations come first when tools can delete, reset, or otherwise change state irreversibly. Rich documentation still matters, but a clear warning about consequence is the minimum control for high-risk actions. In practice, teams should fix both, then validate that the agent can distinguish safe reads from destructive calls before the server is approved for production.
Why the warning should come before the description
When a tool can change state irreversibly, the first job is to make the consequence visible at the point of use. Safety annotations tell the model and the operator that this is not a routine read. Richer documentation helps the system choose correctly, but it is a slower control because it depends on interpretation rather than an explicit risk signal.
A practical rule is to treat annotations as the minimum viable guardrail for destructive actions, then add documentation to reduce ambiguity. That sequencing matters because a tool description can be complete and still fail to prevent a mistaken call if the agent does not recognise the destructive path as special.
What richer documentation adds after the safety signal exists
Tool documentation becomes more valuable once the safety boundary is clear. It should explain the normal read path, the destructive path, the preconditions for each, and any irreversible side effects. That gives the agent enough context to choose between similar-looking operations and helps reviewers understand why a call is safe or unsafe.
For teams running production agents, the useful distinction is not annotation versus documentation as a binary choice. Safety annotations are about consequence signalling. Documentation is about decision quality. If either is missing, you tend to see the same failure modes: read operations treated as mutable ones, destructive calls buried inside generic tool lists, and operators approving tools without understanding blast radius.
How to decide what to ship first
The first release should focus on the highest-consequence tools, especially delete, reset, revoke, overwrite, and other irreversible state changes. Those tools need a visible warning before they need a polished reference guide. Once the high-risk paths are clearly marked, expand the documentation to cover edge cases, preconditions, rollback limits, and safe alternatives.
Teams should also validate behaviour, not just text. A tool can be documented as dangerous and still be used incorrectly if the agent cannot separate safe reads from destructive calls. The real test is whether the system changes its choice when the consequence label changes, and whether production approval is blocked until that distinction is reliable.
Risk and Threat Considerations
When destructive tools are not clearly annotated, the main risk is accidental or automated misuse of high-impact actions. The failure is often not malicious intent, but poor consequence recognition: a model sees a tool name, not an irreversible operation, and proceeds as if the action were reversible.
Failure mechanism: Weak or delayed safety signalling allows the agent to route destructive calls through the same reasoning path it uses for harmless reads, which increases the chance of deletion, reset, or revocation without adequate checks.
Impact: The result can be lost state, service disruption, failed recovery, or broad operational damage if the tool touches production systems, shared data, or privileged workflows.
Standards & Framework Alignment
This section maps relevant standards and security frameworks to the operational risks and controls described in this guidance.
OWASP API Security Top 10 addresses the attack and risk surface, while NIST SP 800-53 Rev 5 sets the governance and control requirements practitioners need to meet.
| Framework | Control / Reference | Relevance |
|---|---|---|
| OWASP API Security Top 10 | API5 — Broken Function Level Authorization | Tool actions need explicit limits on who can invoke destructive functions. |
| Recommendation — Restrict destructive tool functions to authorised callers and separate them from read-only operations. | ||
| NIST SP 800-53 Rev 5 | AC-6 — Least Privilege | High-risk tool calls should be constrained to the minimum required authority. |
| CM-3 — Configuration Change Control | Irreversible tool actions require controlled approval and traceable change handling. | |
| Recommendation — Limit destructive tool access to the smallest set of identities and conditions needed. Require change control for tools that can modify or erase production state. | ||
Practitioner Guidance
What to prioritise: Mark every irreversible or high-blast-radius tool with a clear consequence warning before polishing longer documentation. That gives reviewers and agents the minimum control needed to distinguish safe reads from destructive calls.
What to verify: Test whether the agent behaves differently for read-only and destructive variants of the same workflow. If it does not, the issue is not documentation volume, it is missing or ineffective safety signalling.
Practitioner takeaway: Rich documentation improves correctness, but safety annotations are the faster and more important first line for irreversible actions because they change behaviour at the decision point.
Related resources from NHI Mgmt Group
- How should security teams prioritise NHI remediation in cloud environments?
- Should organisations prioritise external exposure or internal credential governance first?
- Which control should teams prioritise first for high-risk AI systems: logging or documentation?
- Should IAM teams prioritise orphaned accounts or authorization documentation first?