capture_pending_artifacts

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

With no annotations, the description carries the full burden and does: storage target (SQLite, gzip-compressed), >50MB files skipped and marked oversized, missing files marked lost, cleanup deletes staging files making SQLite authoritative, and dry_run performs no mutation. These are exactly the side effects an agent needs before invoking a mutating backfill.

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?

Front-loads the purpose in one line, then introduces the scan criteria, failure modes, dry_run, and cleanup. Slight redundancy with the schema descriptions for dry_run/cleanup and with the output schema's return list, but every section is scannable and earns its place.

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?

Covers scope, discovery criteria, failure handling, mutation semantics, and the no-op caveat for a mutating tool with no annotations. An output schema exists, so repetition of the return shape is harmless rather than a 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 100%, so both parameters are already documented, capping the ceiling. The description still adds meaning beyond the schema by explaining the consequence of cleanup ('the SQLite copy becomes authoritative') and the conservative default rationale for migrating old trials.

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 ('capture artifact files') and narrows scope precisely: trials with an artifact_path but no rows in trial_artifacts. The backfill framing distinguishes it from the normal capture path used by _finalize_trial, so an agent won't confuse it with capture_bundle or run_trial.

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?

Explicitly says when to use it and when not to: 'Under normal operation this is a no-op — _finalize_trial already captures artifacts automatically. This tool only catches trials that slipped through.' It also documents the dry_run=false condition required to apply changes.

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