driftguard_log_command

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

No annotations are provided, so the description carries the full behavioral burden, yet it discloses almost nothing beyond the record intent. It does not say whether entries are appended and ordered, whether repeated identical commands are deduplicated, whether a prior snapshot/session is required, or what happens on a failed call — all material for a tool named "log" in a drift/snapshot workflow.

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?

A single front-loaded sentence with no filler; the verb and resource come first and the purpose clause follows. It is efficiently sized, though that brevity partly explains the missing behavioral detail rather than reflecting full sufficiency.

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 3-parameter, no-output-schema logging tool the description correctly conveys what gets recorded and why, which is the minimum an agent needs to invoke it. It omits the surrounding workflow context (session/snapshot prerequisites, error behavior, aggregation semantics) that would make it complete.

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 100%, so the schema already explains command, exitCode, and the optional durationMs. The description restates exit code conceptually but adds no new meaning such as format expectations, ordering/sequencing rules, or guidance on when to supply durationMs. Baseline 3 applies.

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?

"Registra un comando eseguito con relativo exit code" names a specific verb (record) and resource (executed command + exit code), and the trailing clause "per comporre la ricetta finale di riproducibilità" states the downstream purpose. That purpose clause also separates it from siblings like driftguard_get_recipe and driftguard_create_snapshot, though no sibling is named explicitly.

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?

Usage is only implied: an agent can infer it should call this after executing a command so the exit code lands in the reproducibility recipe. There is no explicit when-to-use vs. when-not, no statement about whether a snapshot/session must exist first, and no mention of alternatives for recording failures (driftguard_diagnose_failure exists for that).

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