p5_dr_kit

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

With no annotations, the description carries the full burden and does so well: it discloses the write target and path layout, 7-generation retention, SHA256SUMS and VERIFIED markers, and the conditional logic (image only when its id changed, program tree only when the P5 version changed), plus the dry-run behavior when confirm is absent. Missing pieces are permission/auth requirements, expected runtime, and failure/partial-kit behavior, which keeps it from a 5.

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 front-loaded with the purpose, but the whole definition is a single run-on sentence with nested parentheticals ('(sqlite3 .backup, integrity_check)', '(docker save, only when its id changed)') that make it hard to scan. Almost every clause is substantive, yet the content would be clearer as a short list. Density is costing readability rather than padding.

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 mutation tool with no annotations and no output schema, the description is unusually complete: contents, retention, verification, conditional inclusion, and dry-run are all covered. The main gap is that <backupDir> is not a parameter and its source (env var? config? default?) is never explained, so an agent cannot predict where output lands without outside knowledge.

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 100% and both parameters already carry their own descriptions ('List existing generations instead', 'Must be true to actually run'), so the schema does the heavy lifting. The description adds one genuinely useful semantic beyond the schema — that omitting confirm returns a plan with sizes — but repeats the status:true meaning verbatim. Baseline 3 is appropriate.

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 names the specific artifact produced (a DR kit under <backupDir>/p5-dr-kit/<stamp>/) and enumerates its contents: sqlite3 .backup copies with integrity_check, the compose project, the running image via docker save, the P5 program tree, and kit-small.tar.gz. That is far more specific than a restatement of the name, and the 'for the P5 server itself (docker mode only)' scoping implicitly separates it from container_backup and p5_config_backup. It stops short of 5 because no sibling is named as an alternative and the operative verb ('builds/creates a kit') is implied by a noun phrase rather than stated up front.

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?

'docker mode only' and 'Requires confirm:true; without it the plan with sizes is returned' are real usage constraints that tell an agent how to invoke it safely. However, there is no statement of when to pick this over p5_config_backup or container_backup, no exclusions, and no prerequisites (e.g., that docker must be running). Usage is implied rather than guided.

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