aiworkhub_manager_task_archive

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

With no annotations, the description carries the burden and does well: it discloses the refusal rule (processing cards are skipped, shown in dry-run), that audit history is preserved, the write gate plus verified manager actor per item, one audit event per task, and per-id receipt shape. It omits reversibility/restore path and idempotency behavior on re-archiving, which keeps it short of 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?

Front-loaded with the mode and the key safety property, then targets, then preview, then guarantees and return shape – no sentence is filler. The dense telegraphic style is justified for an 8-parameter destructive tool.

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?

An output schema exists, so the receipt shape is only summarized rather than fully documented, which is appropriate. For a no-annotation write tool with 8 undocumented parameters it covers targeting, safety, and outcomes well, but the missing 'reason' semantics and selector value formats leave a small residual 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 0%, so the description must compensate, and it does for most parameters: it explains task_id vs task_ids (with the <= 200 cap, which is not in the schema), the four selector fields and their conjunctive semantics, and dry_run's preview behavior including refused ids. The 'reason' parameter and the accepted 'status' values are never mentioned, leaving two real gaps.

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 (archive cards) with an explicit scope qualifier (non-processing only, audit history preserved) and a 'MANAGER WRITE' prefix that signals the manager-tier variant. It does not explicitly name the sibling alternatives (aiworkhub_task_archive, aiworkhub_dashboard_task_archive), so the differentiation is implied by tier naming rather than stated.

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?

Gives the three modes of targeting (single id, id list <= 200, or a conjunctive selector) and recommends dry_run=True to preview before writing, which is actionable routing guidance. It never states when to pick this tool over the adjacent task_archive/dashboard_task_archive siblings, so the agent must infer the manager-only context from the header.

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