POST /hardware/audit

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

Annotations already declare destructiveHint=true, idempotentHint=false, openWorldHint=true and readOnlyHint=false, so the safety profile is covered structurally. The description adds nothing beyond annotations: it does not say what auditing actually changes (audit log entry, last_audit_date, next_audit_date), whether it is reversible, or that confirm=YES may be required. For a destructive, non-idempotent write, that is a clear gap.

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?

It is short and front-loaded, but the front-loading is the redundant HTTP path and the trailing "Generated from Snipe-IT OpenAPI operation hardwareaudit." is pure filler. Two of three clauses carry no decision-relevant information.

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 mutation with a nested body and no output schema, the definition should at minimum describe the audit side effects and body field meanings. Instead it gives one sentence of purpose plus generator metadata, leaving the agent under-informed for a write that changes asset records.

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 50% (only the confirm param is documented in-schema), and the description does not compensate at all. The nested body fields asset_tag (required), location_id and next_audit_date are never explained — an agent gets no hint about whether location_id reassigns the asset or whether next_audit_date is a date format string.

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?

"Mark an asset as audited" is a specific verb+resource, which is better than tautology. But the description never distinguishes this from near-identical siblings such as snipeit_audit_hardware and snipeit_gen_post_auditid, leaving an agent unable to choose between them. The leading HTTP path restates the title rather than adding meaning.

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?

There is no statement of when to use this operation versus the many overlapping audit/update siblings, and no prerequisites such as the asset needing to already exist or be assigned. The only implied guidance comes from the word "audit" itself.

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